projectdoc Toolbox 2.1.0 Release Notes

Phantom References, Nameless Documents, Table Macros, and enhanced Page Tree Support

Today we released version 2.1.0 of the projectdoc Toolbox on the Atlassian Marketplace!

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!

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.

Release Notes Overview
 

New and Noteworthy

The following changes may be the most interesting of this release.

Phantom References

With this version property macros (e.g. Display Document Properties Macro or Display Document Property Macro) support phantom references.

This change does change the semantics of references. A document references another document regardless of the existence of the referenced document.

Nameless Documents

The default use case for the projectdoc Toolbox assumes that there is a page blueprint for each doctype. But users employ user templates instead of writing page blueprints.

To serve this group of users better, we decided to add support for document title and document name syncing. projectdoc is based on projectdoc documents. projectdoc documents require a name. Other than the document title, the document name does not need to be unique within a space. Nameless documents still require a name, but it does no longer be explicitly set. The name can be derived from the document title.

Prior to version 2.1 of the projectdoc Toolbox the title only was derived from the name, typically adding some more characters to the title to meet the uniquness constraint. With version 2.1 users may set a title and have the same character sequence also for the name (which makes the name unique). In addition to set a regular expression can be used to derive a name from the page title. The regular expression can be set on space level with a space property for all documents or just for specific document types.

Space properties to configure nameless documents are

  1. Doctype Star Document Name Pattern
  2. Doctype Document Name Pattern
  3. Default Group Name Pattern
  4. Doctype Document Name Pattern Group

Name List UI

The Name List Macro provides a new UI to keep the table row height in the document properties table in edit mode smaller.

Delete Tree Support

Based on phantom references the execution for a delete tree is much faster due to optimizing the number of documents that need to be updated.

Changed Reindexing

Reindexing of documents is now based on queueing implementations which makes saving documents quite fast.

Table Merger Macro

If you need to combine the results of a Display Table Macro and a manually defined list of entries - for instance by use of the Tour Macro, the new Table Merger Macro allows to render multiple tables in just one table. It also allows to select on and rearrange table columns. The macro can include tables from any source, which includes tables transcluded with the Transclusion Macro.

Table Set Macro

The Table Set Macro applies a simple set operation on tables in its body. This way authors may run operations like and, or, and not on tables.

Breaking Changes

The following changes break features from previous versions of the projectdoc Toolbox.

Please check carefully before updating to this version of the add-on!

Key Summary T P Status Resolution
PDAC-852 Select Document Name Property from Title Property New Feature Major Done Fixed
1 issue

Upgrade Instructions

The following topics have to be considered for an upgrade to this version.

Install the new OBR of the projectdoc Toolbox first.

Required Add-on Updates

The following add-ons need to be updated to work with this version of the projectdoc Toolbox.

Add-on for the projectdoc Toolbox Required Version
Core Doctypes
10.0.0
Doctypes for Agile Planning
8.0.0
Web API Extension
3.0.0
Maven Extension
3.0.0
Graph Extension
1.0.0.b2

List of Changes

The complete list of changes for this release.

The following changes are part of the latest projectdoc Toolbox for Confluence.

Key Summary T P Status Resolution Description
PDAC-864 Table Set Macro New Feature Critical (migrated) Done Fixed

Provide a macro to merge tables based on set operations.
PDAC-860 Table Merger Macro New Feature Critical (migrated) Done Fixed

Provide a macro to merge tables and definition lists.
PDAC-848 Phantom References New Feature Critical (migrated) Done Fixed

Allow phantom references for display property (and related) macros.

Phantom references will make deletions easier and help to find flaws in a documentation where documents reference documents that do not exist.
PDAC-852 Select Document Name Property from Title Property New Feature Major Done Fixed

Allow create a default name for a document based on a page title and a regular expression.

The regular expression is defined on space level.

  • projectdoc.doctype.*.document.name-pattern
  • projectdoc.doctype.*.document.name-pattern.group
  • projectdoc.doctype.(doctype).document.name-pattern
  • projectdoc.doctype.(doctype).document.name-pattern.group
PDAC-859 Use Queueing Confluence Indexer Improvement Critical (migrated) Done Fixed

Use a queueing indexer for Confluence interfacing with Lucene.
PDAC-863 Improve Speed of Space Removals Improvement Major Done Fixed

Removing a space is quite slow since all documents are updated during the removal process.
PDAC-862 Provide Link to Delegate Document Improvement Major Done Fixed

We should provide a link to the delegate document to make it easier to reference properties in that document.
PDAC-854 Support Restore Event Improvement Major Done Fixed

On restoring a document, the documents should be updated.
PDAC-851 Allow Name Property to default to Page Title Improvement Major Done Fixed

For use cases working with user templates providing a title and a name is redundant. Since user template have the notion of a title, projectdoc should support to default to the title for the name property if no name propertyvalue is provided.
PDAC-847 Remove Cleanup Service from Indexer Improvement Major Done Fixed

Currently the indexer is allowed to dump pages that are no longer projectedoc documents. This is redundant and parts may need to move to the persistency layer.
PDAC-846 Improve editor UX for Name List Macros Improvement Major Done Fixed

Improvement of the UX of the name-list macro and tag-list macro.

changes to:
PDAC-845 Delete Table Tree and projectdoc Metadata Improvement Major Done Fixed

projectdoc refeshes metadata whenever a page is deleted. On a page delete this usually results in more processing time. While a delete tree without projectdoc is almost instant, a larger tree requires quite a long time to be removed if projectdoc pages are involved.

We need a more intelligent algorithm to check of required metadata updates and provide means to not update pages that are about to be deleted.

Some of the work may also be done asynchronously.
PDAC-844 Copy Page Tree and projectdoc Metadata Improvement Major Done Fixed

The order in which pages are stored is significant for projectdoc. Pages indexed in the wrong order (e.g. the child page before the parent page) will result in incomplete metadata (e.g. the child page will not know its parent page).

A copy tree provides some issues for the metadata calculation.

  1. Links are updated in a long running task after the tree has been completed
  2. Some links are never updated

Therefore the information of properties may be wrong.

Currently the only workaround is to refresh (e.g. reindex) the page tree after the long running task started by Confluence has been completed. This is currently a manual task, but should be automated. We also need a more intelligent refresh method than simply refreshing from root to leaves and/or leaves to root.
PDAC-855 Ancestor Update on Name Change fails Bug Critical (migrated) Done Fixed

Updating ancestor information fails.

This is due to a bug in the reference calculation: it uses the new name of the document instead of the old. Prior to that the page ID has been used, which is by nature unaffected by this issue.
PDAC-849 False Positive Recursion Detection Bug Critical (migrated) Done Fixed

Using the Display Property Ref or Display Property Ref Concat Macro runs into a recursion detection where there is actually none, if the property has a Display Property Macro as value.

If the value is  Confluence link, no problem is indicated.
PDAC-857 MarshallerMetricsAnalyticsEvent Overflow Bug Major Done Fixed

Due to rendering of properties the MarshallerMetricsAnalyticsEvent runs into an overflow. We should check to run our rendering requests in a batch to run rendering without metrics support.
PDAC-856 Preserve Plain Property Values Bug Major Done Fixed

A set of artificial properties must be saved from being parsed as HTML source.
PDAC-853 Fix Template Parsing for Deep Links Bug Major Done Fixed

Deep Links pointing to a deleted document via a display property macro runs into a parsing failure.
PDAC-850 Transclude Documents Macro fails to render Name Property Bug Major Done Fixed

The Transclude Documents Macro renders the name of a document in the result set verbatim. Instead it should be render the rendered version of the name property.

This is a problem if the name property does contain a macro.
PDAC-861 Page Reference for Delegate Document Bug Minor (migrated) Done Fixed

The artificial page property 'Delegate Document Page Reference' points to the wrong page.
20 issues

Related Releases

Doctype Add-ons

Doctype add-ons provide space and page blueprints based on the projectdoc Toolbox.

Doctype add-ons typically provide blueprints based on macros provided by the projectdoc Toolbox. These add-ons need a licensed version of the projectdoc Toolbox to be installed.

projectdoc Core Doctypes

List of changes in this add-on.

Key Summary T P Status Resolution Description
PDCORED-147 Update to Toolbox 2.1 Improvement Critical (migrated) Done Fixed

Due to an internal API update.
PDCORED-142 Person References on Stakeholder Template Improvement Major Done Fixed

Currently the person dependent properties are referenced by document name and doctype. But moving the document to another space will require to specify the space where the document is found. Removing the doctype information will find the document by title.
PDCORED-145 Sort Key for Subdocuments Bug Critical (migrated) Done Fixed

Doctypes Association, Excerpt, Section, Step fail to calculate the Sort Key.
PDCORED-144 Excerpt Localization Issue Bug Minor (migrated) Done Fixed

The excerpt doctype fails to translate excerpt to Exzerpt, using Excerpt instead (and at one location "Abschnitte".

Displays only in wizard.
PDCORED-143 Typo in Index Space Wizard Bug Minor (migrated) Done Fixed

"a Index" -> "an Index"
5 issues

projectdoc for Agile Planning

List of changes in this add-on.

Key Summary T P Status Resolution Description
PDAGILE-53 Update to Toolbox 2.1 Improvement Critical (migrated) Done Fixed

Due to an internal API update.
PDAGILE-52 Fix CSS on Space Homepage Bug Minor (migrated) Done Fixed

The panel for content content organization is marked with the wrong CSS class. Instead of 'projectdoc-dashboard-panel-core' the class 'projectdoc-homepage-panel-core' should be used.
2 issues

Extension Add-ons

Extension add-ons extends the functionality of the projectdoc Toolbox.

Extension add-ons for the projectdoc Toolbox provide additional features. Extensions need a licensed version of the projectdoc Toolbox to be installed.

Maven Extension

List of changes in this add-on.
PDEXMVN-18 Update to Toolbox 2.1 Improvement Critical (migrated) Done Fixed

Due to an internal API update.
1 issue

Web API Extension

List of changes in this add-on.
PDEXWAPI-20 Update to Toolbox 2.1 Improvement Critical (migrated) Done Fixed

Due to an internal API update.
1 issue

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.