projectdoc Toolbox 6.0 Release Notes

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.

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. 

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.

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
projectdoc for Java Developers
projectdoc for Maven Developers

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.

Example: Error Log from the Browser's Console
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

Key Summary T P Description Fix Version/s
PDAC-1689 Upper Limit for projectdoc Queries Improvement Blocker (migrated)

To be DC compliant the projectdoc Toolbox needs to put an upper limit to the result set. This is to be a configuration option in the administration screen and defaults to a value of 100.

In case the result set is actually larger than 100 hits, the macros need to render a box with a warn message. Users should then put additional constraints on their queries.

It may make sense to provide paging in a future version of the projectdoc Toolbox. Since the design goal is to be printable, the paging would only be an alternative representation of the warning box. There will be no alternative view for PDF export where the query renders more than the specified maximum of hits, since this would violate the DC requirements.

6.0.0
PDAC-1699 Form Identifiers Bug Minor (migrated)

The identifier used in forms for the space and page blueprints are not escaped properly in Confluence. So there are issues with the chosen syntax that contains dots as separators.

Since the issues are not being resolved soon, we need to replace the separators with underscores.

6.0.0

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.

  1. Install the new OBR of the projectdoc Toolbox.
  2. Check if extensions are required to be installed for your use cases
  3. 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:

  1. projectdoc Toolbox
  2. extension add-ons (start with Web API Extension)
  3. 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. (smile)

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.

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

Key Summary T P Description
PDAC-1692 Async Event without Domain Object Improvement Blocker (migrated)

Required to remove load from the async events to update documents when stale information has been encountered on read.

PDAC-1689 Upper Limit for projectdoc Queries Improvement Blocker (migrated)

To be DC compliant the projectdoc Toolbox needs to put an upper limit to the result set. This is to be a configuration option in the administration screen and defaults to a value of 100.

In case the result set is actually larger than 100 hits, the macros need to render a box with a warn message. Users should then put additional constraints on their queries.

It may make sense to provide paging in a future version of the projectdoc Toolbox. Since the design goal is to be printable, the paging would only be an alternative representation of the warning box. There will be no alternative view for PDF export where the query renders more than the specified maximum of hits, since this would violate the DC requirements.

PDAC-1687 Strict Checks for Logability of REST API Parameters Bug Critical (migrated)

Check all parameters for characters that may harm the log file. Currently we sanitize the parameters before logging, but we need to make sure that the log is not manipulated after the first check. Therefore we now reject all requests where harmful characters are contained in request parameters. 

PDAC-1676 No-Property Properties New Feature Critical (migrated)

Allow to add macros as dynamic values to the document properties table and treat them as fragments to render, but no real properties.

These no-property properties cannot be used when rendering other properties and they are neither stored to Lucene nor to AO. They are simply accessible (like sections) in their rendered form, but have not the concept of a normalized value.

PDAC-1695 Editor Sections Macro Chrome Bug Major

The script that renders the chrome for macros to be expanded fails in some use cases. Then the chrome of the macro (especially the title of the section macros) is no longer visible.

A workaround in some use cases is to revert the page. This removes all changes to the draft, but the macros are rendered correctly.

PDAC-1691 Index Card Input Issue Bug Major

The body of the Index Card Macro must be set to plain text to successfully select items. Currently it is set to rich text.

PDAC-1685 Update on Doctype Cache fails Bug Major

When the doctype cache is cleared, then not all service runs detect that the whole cache is to be restored. Some use cases only add the doctype information that has been requested with a cache miss.

The workaround is to clear the doctype cache manually.

PDAC-1705 Support Count for Template List Improvement Major

Allow the count encoding to be used in the Display Template List. Instead of the value, the count of list items or table rows will be rendered, similar to the Display Table.

PDAC-1700 Make identifying Artificial Properties single-values per default Improvement Major

If a property value contains a comma, which is the default separator for list items, then a user may take advantage of the is-single-value control to specify that this value is required to be taken as a single value.

The user has not this control over artificial properties, like the Title.

We need to make the Title and the identifying artificial properties single values per default. This includes, for instance, projectdoc.doctype.common.name, but not Name. For Name the user has control over how to interpret the value and we do not want to interfere with existing use cases.

PDAC-1677 Treat Properties with dynamic Value as no-property New Feature Major

To remove obstacles from users using any kind of projectdoc macros, we need to detect dynamic values as property values and automatically flag those properties as no-property.

In case such a property should be treated as a property, it requires the control force-property.

PDAC-1663 Dynamic Value Detection New Feature Major

Allow to configure the system to prevent the use of dynamic macros as property values.

If a dynamic macro is used as a property value, an error message will be rendered on that page and the incident is logged to the health logger.

PDAC-1660 Calculation Macro New Feature Major

Provide macro to run calculations on a set of result documents and renders the results.

PDAC-1709 Fix Image Paths for PDF Context Bug Minor (migrated)

When rendering the PDF version of a page, the rendering of the box icons fails in some contexts. No icon is rendered.

PDAC-1704 Missing Context Properties Bug Minor (migrated)

When running rendering we need to copy the macro metadata, if present. Otherwise the location of the macro on the page fails.

PDAC-1703 Quirk Mode to suppress In-Document Links Bug Minor (migrated)

When printing the intra-document links are not always rendered properly. The print-quirk-mode named suppress-in-document-links should allow to suppress the rendering of this links (currently only supported by the In-Document Link Macro).

PDAC-1702 Fix PDF export CSS Bug Minor (migrated)

The export to PDF fails to render the steps with step numbers and the boxes with icons.

Also the UI controls are exported to PDF. This should not be the case.

We also need to check the location of the UI controls for the steps.

PDAC-1701 Merge DL with Table Merger on any Depth Bug Minor (migrated)

The Table Merger Macro fails to merge definition lists in case the root of the list is not top level even if marked with the class selector.

In case the selector is used, for instance with the Tour Macro, the Table Merger Macro must be able to do the merge.

PDAC-1699 Form Identifiers Bug Minor (migrated)

The identifier used in forms for the space and page blueprints are not escaped properly in Confluence. So there are issues with the chosen syntax that contains dots as separators.

Since the issues are not being resolved soon, we need to replace the separators with underscores.

PDAC-1698 Section Heading Start Bug Minor (migrated)

The section heading on the separate pages fails to start with the correct level. Instead the level 1 always starts with 0.

PDAC-1697 I18n missing on Page Creation Bug Minor (migrated)

In case an error occurs the message texts are not supported by I18N, instead the keys are rendered.

PDAC-1696 Prevent Blog Posts as projectdoc Documents Bug Minor (migrated)

Currently only pages are considered to be projectdoc documents. In case of a blog post, we need to reject the parsing of the abstract page.

PDAC-1694 Use of Verbose Logging Bug Minor (migrated)

Collision with the Userscripts app: When the configuration is checked, it is checked for both apps.

PDAC-1693 Macro Context NPE Bug Minor (migrated)

When the macro context is created outside a conversion context (i.e. not in a context where a macro is run), then a NPE is rendered.

The context must be detected ant the NPE prevented.

PDAC-1690 Documentation Link for Index Card Macro Bug Minor (migrated)

The link is broken due to a typo.

PDAC-1688 Text for projectdoc Rebuild on Admin Screen Bug Minor (migrated)

The text

"During the rebuild the site should be in read-only mode and is probably not usable. Note that the projectdoc Toolbox provides REST services to run the process on sets of spaces."

is not correct.

For one, it is not the site that is not usable, but the spaces with projectdoc documents that have not already been rebuilt.

Second, it is not possible to do an upgrade or an rebuild on single spaces. These two modes can only be run on a site. The documentation of the REST services address this correctly.

The text should read:

"During the rebuild the spaces with projectdoc documents are probably not usable. Consider to set them read-only. The process may complete quicker, if every space with projectdoc documents has a projectdoc homepage."

We should also render the link to the manual in the projectdoc Refresh section.

PDAC-1686 Add missing Documentation for indexer/find Service Bug Minor (migrated)

The documentation for the indexer/find service is not shown in the REST API Browser.

PDAC-1680 Typos in Display Texts (DE) Bug Minor (migrated)

There are a couple of typos and character issues in the resource bundle for DE.

PDAC-1678 Typos in Display Texts (EN) Bug Minor (migrated)

There are a couple of typos and character issues in the resource bundle for EN.

PDAC-1708 Provide Document Cache on Login Page Improvement Minor (migrated)

In case a projectdoc document is accessed on the login page, then the document cache should be provided. Since we are using an allow list here, we need to add the login page.

PDAC-1706 Default Version 1.0.0 Improvement Minor (migrated)

Assign a version property not supplied with the page wizard with a value of "1.0.0".

PDAC-1681 Support Short Circuit Name List Queries Improvement Minor (migrated)

Instead of fetching the property values from fetched documents, the values can now be directly fetched from the Lucene result set.

This applies only for the Name List Macro and only in use cases where it is allowed by the configuration (de.smartics.projectdoc.name-list.use-short-circuit-result-sets=true) and the template parameter is not used.

PDAC-1679 Parameter Order of Name Body List Macro Improvement Minor (migrated)

Align the parameter order of the Name Body List Macro with the order of parameters of the Name List Macro.

This includes adding the default-to parameter.

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

Web API Extension

The following changes are part of the latest Web API Extension.

Key Summary T P Status Resolution Description
PDEXWAPI-72 No-Property Properties Support New Feature Critical (migrated) Done Fixed

The Web API support for properties that are not real properties, but fragments to access and render.

PDEXWAPI-74 API Update to projectdoc Toolbox 6.0 Improvement Blocker (migrated) Done Fixed

Changes to the internal API of the projectdoc Toolbox require updates in this extension.

PDEXWAPI-75 Limit Size of Result Set Bug Blocker (migrated) Done Fixed

If the page size is not explicitly specified, the limiting of the result set fails.

We need to make sure that the default of 10 hits per page is properly set and that the specified value is limited by the value configured by the administration.

This function is required to be approved for Atlassian Data Center.

PDEXWAPI-73 Strict Checks for Logability of REST API Parameters Bug Critical (migrated) Done Fixed

Check all parameters for characters that may harm the log file. Currently we sanitize the parameters before logging, but we need to make sure that the log is not manipulated after the first check. Therefore we now reject all requests where harmful characters are contained in request parameters. 

PDEXWAPI-71 Comment Issue in API Docs Bug Minor (migrated) Done Fixed

Services that allowed the new version flag in previous versions have the commented description of the removed property in their API documentation.

Information Systems Extension

The following changes are part of the latest Information Systems Extension.

Key Summary T P Status Resolution Description
PDEXINFOSY-50 API Update to projectdoc Toolbox 6.0 Improvement Blocker (migrated) Done Fixed

Changes to the internal API of the projectdoc Toolbox require updates in this extension.

Maven Extension

The following changes are part of the latest Maven Extension.

Key Summary T P Status Resolution Description
PDEXMVN-30 API Update to projectdoc Toolbox 6.0 Improvement Blocker (migrated) Done Fixed

Changes to the internal API of the projectdoc Toolbox require updates in this extension.

PDEXMVN-31 Page Creation Issue Bug Minor (migrated) In Progress Unresolved

Update required due to internal API change in the projectdoc Toolbox.

Doctype Add-ons

The following doctype add-ons are required 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.

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.

Core Doctypes

The following changes are part of the latest Core Doctypes Add-on

Key Summary T P Status Resolution Description
PDCORED-299 Update to projectdoc 6.0 Improvement Blocker (migrated) Done Fixed

Update required due to change of internal API of the projectdoc Toolbox version 6.0.

PDCORED-298 DC Support Improvement Major Done Fixed

The app's configuration has to be updated to reflect the approval for Confluence Data Center by Atlassian.

PDCORED-300 Form Identifiers Bug Minor (migrated) Done Fixed

The identifier used in forms for the space and page blueprints are not escaped properly in Confluence. So there are issues with the chosen syntax that contains dots as separators. Since the issues are not being resolved soon, we need to replace the separators with underscores.

Doctypes for Agile Planning

The following changes are part of the latest Doctypes for Agile Planning.

Key Summary T P Status Resolution Description
PDAGILE-106 Update to projectdoc 6.0 Improvement Blocker (migrated) Done Fixed

Update required due to change of internal API of the projectdoc Toolbox version 6.0.

PDAGILE-105 DC Support Improvement Major Done Fixed

The app's configuration has to be updated to reflect the approval for Confluence Data Center by Atlassian.

PDAGILE-108 Core Services Dependency Bug Major Done Fixed

The dependency to the Core Services cannot be resolved by the User Story Macro.

PDAGILE-107 Form Identifiers Bug Minor (migrated) Done Fixed

The identifier used in forms for the space and page blueprints are not escaped properly in Confluence. So there are issues with the chosen syntax that contains dots as separators. Since the issues are not being resolved soon, we need to replace the separators with underscores.

projectdoc Developer Diaries

The following changes are part of the latest projectdoc Developer Diaries.

Key Summary T P Status Resolution Description
DEVDIARY-149 DC Support Improvement Major Done Fixed

The app's configuration has to be updated to reflect the approval for Confluence Data Center by Atlassian.

DEVDIARY-150 Form Identifiers Bug Minor (migrated) Done Fixed

The identifier used in forms for the space and page blueprints are not escaped properly in Confluence. So there are issues with the chosen syntax that contains dots as separators. Since the issues are not being resolved soon, we need to replace the separators with underscores.

Doctypes for Project Management

The following changes are part of the latest Doctypes for Project Management.

Key Summary T P Status Resolution Description
PDPRJMGMT-92 DC Support Improvement Major Done Fixed

The app's configuration has to be updated to reflect the approval for Confluence Data Center by Atlassian.

PDPRJMGMT-93 Form Identifiers Bug Minor (migrated) Done Fixed

The identifier used in forms for the space and page blueprints are not escaped properly in Confluence. So there are issues with the chosen syntax that contains dots as separators. Since the issues are not being resolved soon, we need to replace the separators with underscores.

Doctypes for Service Management

The following changes are part of the latest Doctypes for Service Management.

Key Summary T P Status Resolution Description
SERVICES-53 DC Support Improvement Major Done Fixed

The app's configuration has to be updated to reflect the approval for Confluence Data Center by Atlassian.

SERVICES-55 Version Number Handling for Release Doctype Improvement Minor (migrated) Done Fixed

Provide a version number default if no number is specified.

SERVICES-54 Form Identifiers Bug Minor (migrated) Done Fixed

The identifier used in forms for the space and page blueprints are not escaped properly in Confluence. So there are issues with the chosen syntax that contains dots as separators. Since the issues are not being resolved soon, we need to replace the separators with underscores.

Doctypes for Business Strategy

The following changes are part of the latest Doctypes for Business Strategy.

Key Summary T P Status Resolution Description
STRATEGY-37 DC Support Improvement Major Done Fixed

The app's configuration has to be updated to reflect the approval for Confluence Data Center by Atlassian.

STRATEGY-38 Form Identifiers Bug Minor (migrated) Done Fixed

The identifier used in forms for the space and page blueprints are not escaped properly in Confluence. So there are issues with the chosen syntax that contains dots as separators. Since the issues are not being resolved soon, we need to replace the separators with underscores.

Doctypes for Software Development

The following changes are part of the latest Doctypes for Software Development.

Key Summary T P Status Resolution Description
PDSWDEVD-170 DC Support Improvement Major Done Fixed

The app's configuration has to be updated to reflect the approval for Confluence Data Center by Atlassian.

PDSWDEVD-171 Form Identifiers Bug Minor (migrated) Done Fixed

The identifier used in forms for the space and page blueprints are not escaped properly in Confluence. So there are issues with the chosen syntax that contains dots as separators. Since the issues are not being resolved soon, we need to replace the separators with underscores.

projectdoc arc42 Template

The following changes are part of the latest projectdoc Add-on for arc42.

Key Summary T P Status Resolution Description
ARCFOURTWO-81 DC Support Improvement Major Done Fixed

The app's configuration has to be updated to reflect the approval for Confluence Data Center by Atlassian.

ARCFOURTWO-84 Cannot create Sections Bug Minor (migrated) Done Fixed

New section pages cannot be created with the blueprint wizard.

ARCFOURTWO-83 Conventions Section Text Bug Minor (migrated) Done Fixed

The text shown in the Conventions Section in the Constraints Section shows the text for the Organizational Constraints.

ARCFOURTWO-82 Form Identifiers Bug Minor (migrated) Done Fixed

The identifier used in forms for the space and page blueprints are not escaped properly in Confluence. So there are issues with the chosen syntax that contains dots as separators. Since the issues are not being resolved soon, we need to replace the separators with underscores.

Doctypes for Teamwork

The following changes are part of the latest Doctypes for Teamwork.

Key Summary T P Status Resolution Description
PDTEAMWORK-44 DC Support Improvement Major Done Fixed

The app's configuration has to be updated to reflect the approval for Confluence Data Center by Atlassian.

PDTEAMWORK-45 Form Identifiers Bug Minor (migrated) Done Fixed

The identifier used in forms for the space and page blueprints are not escaped properly in Confluence. So there are issues with the chosen syntax that contains dots as separators. Since the issues are not being resolved soon, we need to replace the separators with underscores.

Doctypes for V-Modell XT

The following changes are part of the latest Doctypes for V-Modell XT.

Key Summary T P Status Resolution Description
PDVMXT-46 DC Support Improvement Major Done Fixed

The app's configuration has to be updated to reflect the approval for Confluence Data Center by Atlassian.

PDVMXT-47 Form Identifiers Bug Minor (migrated) Done Fixed

The identifier used in forms for the space and page blueprints are not escaped properly in Confluence. So there are issues with the chosen syntax that contains dots as separators. Since the issues are not being resolved soon, we need to replace the separators with underscores.

Resources

Release Notes for the projectdoc Toolbox
Relevant information on changes to the projectdoc Toolbox for Confluence introduces by new versions of this app.
Glossary
Terms used in and defined for projectdoc.
FAQs
Questions and answers related to the projectdoc Toolbox and Confluence.