projectdoc Toolbox 4.7 Release Notes

Artificial Document Properties on Metadata, Tasks Report Macro, Section Compilations, Usability enhancements and more.

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

This release provides new features, improvements, and bugfixes.

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

Artificial Document Properties on Metadata

This release collects metadata to allow documentation gardners to find referencing documents easier.

Information on property names, controls, and values is collected as well as on document part identifiers and tags.

The following artificial properties support queries for documents that define a given name.

The query matched no documents.

The following artificial properties support queries for documents that use a given name by reference.

The query matched no documents.

More information on this topic is available at Name Refactorings.

A reindex is required to add the new properties (see Upgrade Instructions below).

Tasks Report Macro

The new Tasks Report Macro allows to select Confluence Tasks from projectdoc Documents selected by a Where constraint.

The new macro simply configures the Confluence Task Report Macro and executes it. The new macro is not a replacement. In case users want to select on spaces, pages, and labels, the original macro is still in charge. The new macro simply connects projectdoc documents to the world of Confluence Tasks.

Section Compilations

In software product documentation there is a good chance to encounter elements that are reused. For instance a parameter of a collection of macros. Suppose there is a collection of macros that transclude content from a single document. Each of these macros would provide a parameter named "Document" to link to the document to transclude from. Often the documentation for this parameter is identical. Therefore the documentation for the Document Parameter is in one location and the macros transclude this content.

The macros may need to control the order of their parameters. Maybe the first macro has the Document Parameter as its second parameter while all others specify it as their first.

In addition to that some macros may provide parameters they do not share with other macros. So authors may want to document these parameters in sections on the macro documentation document.

In this use case the Section Compiler by Reference Macro is of great support. The body of the macro holds the sections that document parameters the macro does not share. These sections may be in any order. The Section Compiler by Reference Macro references a property that defines the order of all parameters that are to be included in the macro document's documentation. Each reference may refer to a document that contains share information about a parameter or a section in the macros body.

This way it is very easy to mix and merge parameter documentation that is shared with information that has been defined locally.

Usability Enhancements

Autocomplete support is increased by supporting transclusion references ( PDAC-1315 - Autocomplete for Transclusion Reference Done ) and property names in drafts ( PDAC-1312 - Property Name Autocomplete in Draft Mode Done ).

The property name for the Display Document Property Macro is now a mandatory property ( PDAC-1314 - Require Property Name for Display Property Done ). Although the default would still be the name of the referenced document, by enforcing to specify a name the macro editor automatically pops up. Since the reference is often not to the name property, this update does better support the usability.

For Scroll Word Exporter (formerly known as Scroll Office) the projectdoc Toolbox now autodetects the required quirk mode ( PDAC-1324 - Scroll Office Auto Mode Done ).

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.

Installation Order

Please install the projectdoc Toolbox first, then the extensions and finally update the doctypes.

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)

Reindex

Due to the following issues a reindex is required to update properties.

Key Summary T P Description
PDAC-1310 Add Artificial Properties for Refactorings New Feature Critical (migrated)

Check property Names from Select, Where, and Sort By and display property macro names.

Also add the names of the properties defined in the document.

Add additional properties for controls, values, macros, CSS.
PDAC-1309 Add Intros and Extros to Lucene Index Improvement Major

Besides titles for sections and boxes also the intro and extro text should also be added to the Lucene text index.
2 issues

In case you do not use any of these features, there is no need for a reindex.

Please refer to Troubleshooting Reindexer for projectdoc Documents for details on how to reindex projectdoc documents.

List of Changes

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

Key Summary T P Description
PDAC-1320 Section Compiler by Reference New Feature Critical (migrated)

Provide a macro that allows authors to easily mix reusable content with local sections.

The use case is a list of entities that are either described in local sections or by documents from which selected sections are transcluded. In either case the elements the macro deals with are sections.
PDAC-1310 Add Artificial Properties for Refactorings New Feature Critical (migrated)

Check property Names from Select, Where, and Sort By and display property macro names.

Also add the names of the properties defined in the document.

Add additional properties for controls, values, macros, CSS.
PDAC-1307 Tasks Report Macro based on projectdoc Filter New Feature Critical (migrated)

To integrate better with Confluence Tasks we need to provide a macro that allows to select on projectdoc properties (with a Where parameter) to fetch Confluence Tasks for the Tasks Report.
PDAC-1319 Linking Support for Transclude Reference Macro New Feature Major

The Transclude Reference Macro should support links to the rendered documents. Either from the heading or by an additional link.

This is similar to the Transclude Documents Macro.
PDAC-1324 Scroll Office Auto Mode Improvement Major

In case Scroll Office is executing and not Print Quirk Mode is set, scroll-office should be set automatically. The same is true for the PDF and Word quirk modes.
PDAC-1316 Add CSS Parameter to Transclude Reference Macro Improvement Major

Provide a parameter to the Transclusion Reference Macro to specify CSS classes to the wrapper element of the transcluded content.
PDAC-1315 Autocomplete for Transclusion Reference Improvement Major

The Ref parameter of the Transclusion Reference Macro should support autocomplete for Property Names.
PDAC-1313 Support Content Marker to Hide on Text Content Improvement Major

The Content Marker Macro should be able to recognize text in its rendered content to decide to not show it. The use case is to hide results of enclosed macros that should be considered as empty or boilerplate text.
PDAC-1312 Property Name Autocomplete in Draft Mode Improvement Major

Support draft documents for the autocompletion of property names (for instance Display Property Macro).
PDAC-1309 Add Intros and Extros to Lucene Index Improvement Major

Besides titles for sections and boxes also the intro and extro text should also be added to the Lucene text index.
PDAC-1308 Rewrite HTML IDs on transcluded Content Improvement Major

The transclusion macros do not ensure that the HTML IDs on the transcluded content are unique.

To generate valid HTML we need to check that no two identifiers are the same.
PDAC-1327 Handle Encodings in Property Names for Sort-By Parameters Bug Major

When encodings are used, the names of document properties are not properly resolved:

Calendar Week@{number}, Date of Birth-@{date}, Down-, Plain, Up+
PDAC-1326 Handle Encodings in Property Names for Select Parameters Bug Major

The property names as values in the Select Parameter may be encoded for linking and alignment.
PDAC-1311 Encoding Problems on Artificial Properties Bug Major

Plain properties need to be HTML encoded for the rendered version. Otherwise the parser fails on character entities.
PDAC-1323 Hide Aside Panel Macro Improvement Minor (migrated)

Provide a parameter to the Aside Panel Macro to allow users to hide it.

For generated panels this is an easy way to temporarily hide the contents until something useful is to show.
PDAC-1321 CSS Class for transcluded Properties Table Improvement Minor (migrated)

The table with document properties that is rendered in front of transcluded content needs to be tagged with a CSS class. This way users may provide specific styles for that table.
PDAC-1314 Require Property Name for Display Property Improvement Minor (migrated)

Since users typically want to specify a property different from this document's name, it should be required to specify a name. This way the macro editor is automatically opened.
PDAC-1325 Fix JavaScript for Blank Doctype Wizard Bug Minor (migrated)

Check that wizard JS is fully loaded is missing.
PDAC-1322 Provide normalized Value for URL and Tiny URL Bug Minor (migrated)

The artificial properties URL and Tiny URL do not provide a normalized version of the original and rendered value. In both cases they should return the plain URL for the normalized version.
PDAC-1318 Preview fails for Transclude Reference Macro Bug Minor (migrated)

The reload button is disabled in case the required parameter has not be recognized as set.
PDAC-1317 Transclude Reference Macro does not require Self Transclusion Check Bug Minor (migrated)

The Transclude Reference Macro is also checking if the current document is in use. The default use case for this macro is to refer to the current document. Therefore the transclusion recursion check should not be run for this macro.
21 issues

Related Releases

Extension Add-ons

The following extension are required to be updated for the projectdoc Toolbox.

Web API Extension

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

Key Summary T P Status Resolution Description
PDEXWAPI-52 Performance Issue on Display Properties Improvement Critical (migrated) Done Fixed

When accessing properties and sections via the REST API, the content is rendered. In case no sections are requested, the sections should not be rendered.

The same holds in case a filter is set. Only the requested sections need to be rendered.

This is especially a performance issue if a section holds a resource intensive macro.
1 issue

Maven Extension

The following changes are part of the latest Maven Extension.

Key Summary T P Status Resolution Description
PDEXMVN-28 Update Setter Injection Bug Critical (migrated) Done Fixed

Fails on new versions of Confluence.
1 issue

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. 

Key Summary T P Status Resolution Description
PDCORED-277 Hide More Info Aside Panel from Readers Improvement Major Done Fixed

The reference on the doctype index page and homepage that provides additional information on the doctype is only relevant for authors. Therefore the aside panel is not shown to readers.
PDCORED-273 Hide Description Sections per Default Improvement Major Done Fixed

The text of the descriptions section is typically the introduction to the document. Therefore the section title should not be shown per default.
PDCORED-276 Remove Wiki Links from Bottom Improvement Minor (migrated) Done Fixed

The reference to the central index page or homepage is not very helpful since all links are also on the right navigation. If the list is really long, users may find a link at the end, but this link is arbitrary. Therefore these links should be removed, improving the layout.
PDCORED-275 Add Workers Property to Charter Improvement Minor (migrated) Done Fixed

The Workers Property allows to specify the names of team members working on the document.
PDCORED-274 Doctype Type Create Template Bug Critical (migrated) Done Fixed

Doctype types generate the wrong blueprint references for their create subtype macro. Also the label is wrong. Both refer to the type's doctype.
PDCORED-278 Fix JavaScript for Doctype Wizards Bug Major Done Fixed

Check that wizard JS is fully loaded is missing.
PDCORED-272 Provide Default Render Classes Bug Minor (migrated) Done Fixed

Macros with remote or context control need default tags so that users may easily use these features without configuration.
7 issues

Doctypes for Agile Planning

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

Key Summary T P Status Resolution Description
PDAGILE-91 Hide More Info Aside Panel from Readers Improvement Major Done Fixed

The reference on the doctype index page and homepage that provides additional information on the doctype is only relevant for authors. Therefore the aside panel is not shown to readers.
PDAGILE-88 Hide Description Sections per Default Improvement Major Done Fixed

The text of the descriptions section is typically the introduction to the document. Therefore the section title should not be shown per default.
PDAGILE-90 Remove Wiki Links from Bottom Improvement Minor (migrated) Done Fixed

The reference to the central index page or homepage is not very helpful since all links are also on the right navigation. If the list is really long, users may find a link at the end, but this link is arbitrary. Therefore these links should be removed, improving the layout.
PDAGILE-89 Doctype Type Create Template Bug Critical (migrated) Done Fixed

Doctype types generate the wrong blueprint references for their create subtype macro. Also the label is wrong. Both refer to the type's doctype.
PDAGILE-92 Fix JavaScript for Doctype Wizards Bug Major Done Fixed

Check that wizard JS is fully loaded is missing.
PDAGILE-87 Provide Default Render Classes Bug Minor (migrated) Done Fixed

Macros with remote or context control need default tags so that users may easily use these features without configuration.
6 issues

projectdoc Developer Diaries

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

Key Summary T P Status Resolution Description
DEVDIARY-134 Hide More Info Aside Panel from Readers Improvement Major Done Fixed

The reference on the doctype index page and homepage that provides additional information on the doctype is only relevant for authors. Therefore the aside panel is not shown to readers.
DEVDIARY-131 Hide Description Sections per Default Improvement Major Done Fixed

The text of the descriptions section is typically the introduction to the document. Therefore the section title should not be shown per default.
DEVDIARY-133 Remove Wiki Links from Bottom Improvement Minor (migrated) Done Fixed

The reference to the central index page or homepage is not very helpful since all links are also on the right navigation. If the list is really long, users may find a link at the end, but this link is arbitrary. Therefore these links should be removed, improving the layout.
DEVDIARY-130 Reorder Person, Stakeholder Improvement Minor (migrated) Done Fixed

To support creating persons before stakeholder, the person must be the first in the list.

This is probably an interims solution since the user may need to select which doctype ID is to be used for the create action.
DEVDIARY-132 Doctype Type Create Template Bug Critical (migrated) Done Fixed

Doctype types generate the wrong blueprint references for their create subtype macro. Also the label is wrong. Both refer to the type's doctype.
DEVDIARY-135 Fix JavaScript for Doctype Wizards Bug Major Done Fixed

Check that wizard JS is fully loaded is missing.
DEVDIARY-129 Provide Default Render Classes Bug Minor (migrated) Done Fixed

Macros with remote or context control need default tags so that users may easily use these features without configuration.
7 issues

Doctypes for Project Management

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

Key Summary T P Status Resolution Description
PDPRJMGMT-75 Hide More Info Aside Panel from Readers Improvement Major Done Fixed

The reference on the doctype index page and homepage that provides additional information on the doctype is only relevant for authors. Therefore the aside panel is not shown to readers.
PDPRJMGMT-72 Hide Description Sections per Default Improvement Major Done Fixed

The text of the descriptions section is typically the introduction to the document. Therefore the section title should not be shown per default.
PDPRJMGMT-74 Remove Wiki Links from Bottom Improvement Minor (migrated) Done Fixed

The reference to the central index page or homepage is not very helpful since all links are also on the right navigation. If the list is really long, users may find a link at the end, but this link is arbitrary. Therefore these links should be removed, improving the layout.
PDPRJMGMT-73 Doctype Type Create Template Bug Critical (migrated) Done Fixed

Doctype types generate the wrong blueprint references for their create subtype macro. Also the label is wrong. Both refer to the type's doctype.
PDPRJMGMT-76 Fix JavaScript for Doctype Wizards Bug Major Done Fixed

Check that wizard JS is fully loaded is missing.
PDPRJMGMT-71 Provide Default Render Classes Bug Minor (migrated) Done Fixed

Macros with remote or context control need default tags so that users may easily use these features without configuration.
6 issues

Doctypes for Service Management

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

Key Summary T P Status Resolution Description
SERVICES-28 Hide More Info Aside Panel from Readers Improvement Major Done Fixed

The reference on the doctype index page and homepage that provides additional information on the doctype is only relevant for authors. Therefore the aside panel is not shown to readers.
SERVICES-25 Hide Description Sections per Default Improvement Major Done Fixed

The text of the descriptions section is typically the introduction to the document. Therefore the section title should not be shown per default.
SERVICES-27 Remove Wiki Links from Bottom Improvement Minor (migrated) Done Fixed

The reference to the central index page or homepage is not very helpful since all links are also on the right navigation. If the list is really long, users may find a link at the end, but this link is arbitrary. Therefore these links should be removed, improving the layout.
SERVICES-26 Doctype Type Create Template Bug Critical (migrated) Done Fixed

Doctype types generate the wrong blueprint references for their create subtype macro. Also the label is wrong. Both refer to the type's doctype.
SERVICES-29 Fix JavaScript for Doctype Wizards Bug Major Done Fixed

Check that wizard JS is fully loaded is missing.
SERVICES-24 Provide Default Render Classes Bug Minor (migrated) Done Fixed

Macros with remote or context control need default tags so that users may easily use these features without configuration.
6 issues

Doctypes for Business Strategy

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

Key Summary T P Status Resolution Description
STRATEGY-22 Hide More Info Aside Panel from Readers Improvement Major Done Fixed

The reference on the doctype index page and homepage that provides additional information on the doctype is only relevant for authors. Therefore the aside panel is not shown to readers.
STRATEGY-19 Hide Description Sections per Default Improvement Major Done Fixed

The text of the descriptions section is typically the introduction to the document. Therefore the section title should not be shown per default.
STRATEGY-21 Remove Wiki Links from Bottom Improvement Minor (migrated) Done Fixed

The reference to the central index page or homepage is not very helpful since all links are also on the right navigation. If the list is really long, users may find a link at the end, but this link is arbitrary. Therefore these links should be removed, improving the layout.
STRATEGY-20 Doctype Type Create Template Bug Critical (migrated) Done Fixed

Doctype types generate the wrong blueprint references for their create subtype macro. Also the label is wrong. Both refer to the type's doctype.
STRATEGY-23 Fix JavaScript for Doctype Wizards Bug Major Done Fixed

Check that wizard JS is fully loaded is missing.
STRATEGY-18 Provide Default Render Classes Bug Minor (migrated) Done Fixed

Macros with remote or context control need default tags so that users may easily use these features without configuration.
6 issues

Doctypes for Software Development

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

Key Summary T P Status Resolution Description
PDSWDEVD-152 Hide More Info Aside Panel from Readers Improvement Major Done Fixed

The reference on the doctype index page and homepage that provides additional information on the doctype is only relevant for authors. Therefore the aside panel is not shown to readers.
PDSWDEVD-149 Hide Description Sections per Default Improvement Major Done Fixed

The text of the descriptions section is typically the introduction to the document. Therefore the section title should not be shown per default.
PDSWDEVD-151 Remove Wiki Links from Bottom Improvement Minor (migrated) Done Fixed

The reference to the central index page or homepage is not very helpful since all links are also on the right navigation. If the list is really long, users may find a link at the end, but this link is arbitrary. Therefore these links should be removed, improving the layout.
PDSWDEVD-150 Doctype Type Create Template Bug Critical (migrated) Done Fixed

Doctype types generate the wrong blueprint references for their create subtype macro. Also the label is wrong. Both refer to the type's doctype.
PDSWDEVD-153 Fix JavaScript for Doctype Wizards Bug Major Done Fixed

Check that wizard JS is fully loaded is missing.
PDSWDEVD-148 Provide Default Render Classes Bug Minor (migrated) Done Fixed

Macros with remote or context control need default tags so that users may easily use these features without configuration.
6 issues

Doctypes for Teamwork

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

Key Summary T P Status Resolution Description
PDTEAMWORK-30 Hide More Info Aside Panel from Readers Improvement Major Done Fixed

The reference on the doctype index page and homepage that provides additional information on the doctype is only relevant for authors. Therefore the aside panel is not shown to readers.
PDTEAMWORK-27 Hide Description Sections per Default Improvement Major Done Fixed

The text of the descriptions section is typically the introduction to the document. Therefore the section title should not be shown per default.
PDTEAMWORK-29 Remove Wiki Links from Bottom Improvement Minor (migrated) Done Fixed

The reference to the central index page or homepage is not very helpful since all links are also on the right navigation. If the list is really long, users may find a link at the end, but this link is arbitrary. Therefore these links should be removed, improving the layout.
PDTEAMWORK-28 Doctype Type Create Template Bug Critical (migrated) Done Fixed

Doctype types generate the wrong blueprint references for their create subtype macro. Also the label is wrong. Both refer to the type's doctype.
PDTEAMWORK-31 Fix JavaScript for Doctype Wizards Bug Major Done Fixed

Check that wizard JS is fully loaded is missing.
PDTEAMWORK-26 Provide Default Render Classes Bug Minor (migrated) Done Fixed

Macros with remote or context control need default tags so that users may easily use these features without configuration.
6 issues

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-30 Hide More Info Aside Panel from Readers Improvement Major Done Fixed

The reference on the doctype index page and homepage that provides additional information on the doctype is only relevant for authors. Therefore the aside panel is not shown to readers.
PDVMXT-27 Hide Description Sections per Default Improvement Major Done Fixed

The text of the descriptions section is typically the introduction to the document. Therefore the section title should not be shown per default.
PDVMXT-29 Remove Wiki Links from Bottom Improvement Minor (migrated) Done Fixed

The reference to the central index page or homepage is not very helpful since all links are also on the right navigation. If the list is really long, users may find a link at the end, but this link is arbitrary. Therefore these links should be removed, improving the layout.
PDVMXT-28 Doctype Type Create Template Bug Critical (migrated) Done Fixed

Doctype types generate the wrong blueprint references for their create subtype macro. Also the label is wrong. Both refer to the type's doctype.
PDVMXT-31 Fix JavaScript for Doctype Wizards Bug Major Done Fixed

Check that wizard JS is fully loaded is missing.
PDVMXT-26 Provide Default Render Classes Bug Minor (migrated) Done Fixed

Macros with remote or context control need default tags so that users may easily use these features without configuration.
6 issues

projectdoc arc42 Template

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

Key Summary T P Status Resolution Description
ARCFOURTWO-73 Fix JavaScript for Blank Doctype Wizard Bug Major Done Fixed

Check that wizard JS is fully loaded is missing.
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.