Easier Linking, Create Links for Name List Macros, more Support for Placeholders in Templates, plus Enhancements to Artificial Properties, Autocomplete, and Deep Links.

Today we released version 4.6 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!

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.

Download the projectdoc Toolbox or visit the projectdoc Toolbox on the Atlassian Marketplace!

New and Noteworthy

Easier Linking

This release adds three macros to make it easier to create links to in your Confluence.

The Wiki Link Macro allows to create dynamic and static links. It originally has been designed to allow space designers to add links in their space templates to documents that do not already exist. With the tooltip feature that renders the Short Description of the document the link points to, the Wiki Link Macro is now also in use by the Template Author. Since the interface of the Wiki Link Macro is difficult to use, because it actually has two purposes, we decided to provide two new macros with the same functionality, but with a more intuitive interface.

Static Document Link Macro: Renders a static link to a projectdoc document in the wiki. A static link is a link to a Confluence page that is identified by its space key and document title.
Dynamic Document Link Macro: Renders a dynamic link to a projectdoc document in the wiki. A dynamic link is a link to a Confluence page that is identified by the page title and the delegate space closure. The target of the link is calculated at render time. In case the delegate space closure changes, a different document may be the target of the link.
Term Link Macro: Renders a dynamic link to a Glossary Item in the wiki.

The advantage using the link macros is the rendering of a tooltip on mouse over. The default tooltip text is the short description of the referenced document.

Another use case is rendering links using a publishing process. Typically there is a set of spaces with which the team works. At publishing time the content of some spaces is copied to the published spaces. Dynamic links allow to render the correct links dependent on the Space Closure.

The following table lists the supported parameters of the three macros.

Use Case	Parameter	Static Link Macro	Dynamic Link Macro	Term Link Macro
Link whole document	Page / Title	Document (Page)	Document Title (Title)	Term (Title)
Link whole document	Space Closure
Link into document	Anchor
Control label	Label
	Lower Case
	Tooltip
	Abbreviation Mode
	CSS Classes
Document creation	Link Rendering Control
Document creation	Blueprint
Remote Control	Request Parameters
Toggle Feature	Request Toggle Label
Toggle Feature	Request Toggle Tooltip

Since the Static Link Macro is referencing a document similar to a Confluence link by space key and page title, there is no need to specify the space key separately. There is also no need to specify the space closure. All other use cases are supported.

The Term Link Macro is designed for simplified use and therefore does not provide parameters for use cases beyond rendering a reference to an item in the glossary. Although a space key is required to calculate the link to a document, the macro does not allow to specify the space closure as a parameter. The delegate space is required to be set correctly. This requires that a space defines its attachment space for glossary items.

Autolinking on Document Creation

The projectdoc Toolbox provides a number of macros that allow to automatically link to documents at the moment they appear. This includes the Wiki Link Macro and the Dynamic Document Link Macro. Some macros are designed to be used a property values, such as the Child Documents Macro or the Parent Property Macro.

With this version the Name List Macro provides the Parent Name Parameter to allow template authors to automatically add the parent documents name to the name list.

The use case for this feature is for template authors. Consider a doctype that is in a close relationship to another doctype, such as a lifecycle and its phases. A phase does reference the lifecycle it belongs to and the lifecycle lists all phases it contains. So a typical location for a phase document would be a child of a lifecycle document. By the use of the Child Documents Macro and Name List Macro the links from a lifecycle to its phases and from a phase to its lifecycle can be automatically created. Since a phase may also be commonly used a number of lifecycles, the value of the lifecycle property of a phase document is required to use the Name List Macro to manually add the names of valid lifecycles where this phase is used.

Currently the Child Documents Macro does not allow to add additional names.

Create Links

The Name List Macro (and its cousins) are rendering create links if the Space Property named Document Creation for Name List is set to true (which is the default value).

This feature also updates links in Name List Macros on creation, rename, and deletion of documents.

This feature requires a reindex of the projectdoc Confluence cache. Please refer to Troubleshooting Reindexer for projectdoc Documents for details.

Update Category Doctype

The Category doctype requires an improvement on defining its name. In previous version of the Core Doctypes the name of the category started with a blank character. With PDCORED-271 - Category Name Improvement Done the name has been corrected. This fix is required by the Create Links Feature to successfully update the link with the Name List Macro.

Template Support for Labels and Tooltips

More macros allow to use property placeholders in labels and tooltips. A property placeholder is a name of a property, surrounded by placeholder delimiters. Here are two examples:

Placeholder Example	Description
${Story Points}	Renders the document property Story Points of the referenced document.
$[Name] (${Story Points})	Renders the Name of the document, with a link, and the Story Points in brackets as text.

With this version the Wiki Link Macro (and its new cousins – see above) supports the use of property placeholders (see PDAC-1277 - Template Support for Wiki Link Label and Tooltip Done ). Also the Cite Macro supports placeholders in tooltips (see PDAC-1280 - Template Support for Cite Macro Tooltip Done ).

A little different is the template support for the Tour Macro. Here the template with property placeholders is now supported in the table column header (see PDAC-1283 - Templates for Tour Macro in Definition List Mode Done ).

According to tooltips: PDAC-1290 - Tooltips for Display Document Properties Macro Done fixes an issues with the Display Document Properties Macro and the rendering of tooltips.

Enhancements to Autocomplete

The following issues enhance the support of the Autocomplete Feature in macros.

PDAC-1286 - Autocomplete for Display Reference Macro Document Property Done
PDAC-1287 - Autocomplete for Doctype Parameter on Document Properties Marker Macro Done
PDAC-1288 - Autocomplete for Parent Doctype of the Parent Macro Done
PDAC-1281 - Remove Duplicates from Name Autocomplete Done
PDAC-1289 - Allow new Doctype IDs for Autocomplete of Name List Macros Done
PDAC-1293 - Name List Macro Single Value Workaround Done

Enhancements to Artificial Properties

With this version users may override any artificial property with a document property.

Artificial properties are automatically created by a predefined name, such as URL. In case your domain model required to define a property named URL, the artificial property prevented the regular use of the URL property.

With this version artificial properties are only created if a property by this name does not already exist.

For the properties named Email and Team Email with e-mail addresses as values, now provide a normalized (the plain email address) and a text version (the label of the link) is now supported.

Enhancements to Deep Links

With this version aggregated values collected via Deep Link are now merged more effectively. Previous versions matched the names by the HTML representation, which failed in case the same name was rendered differently. This version matches the text values of the properties.

Installation Instructions

Due to PDAC-1292 - Override Artificial Properties Done and PDAC-1278 - Support artificial Text Values for Name List Macro Done a reindex is required to update properties.

In case you do not use this feature, there is no need for a reindex.

List of Changes

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

Key	Summary	Description
PDAC-1301	Update Documents with Doctype References	In case a document name is changed, either due to create, delete, or rename, then documents that may reference the document should be removed from the cache. Otherwise the reference to the modified document is still rendered. Which properties reference the document is determined by the internal doctype model. The doctype model is required to calculate the properties to update. If doctypes without model use common properties supported by internal doctype models, the update will take place.
PDAC-1294	Parent Name as Default for Name List Macro	Provide a parameter to the Name List Macro that allows to add the name of the parent in case the doctype of the parent matches one of the specified. This allows template authors to allow their doctype to be added as child document or - when added to the doctype home page - allow to specify the names as normal.
PDAC-1214	Creating Categorizing Documents	When adding a new name to a Name List Macro, users should more easily be able to create the new document in the right location. Since this is not a use case for everyone, we require the space property `projectdoc.allowDocumentCreation.nameList` to be set to `true` (which is the default). Since not everyone uses projectdoc spaces, the system property `de.smartics.projectdoc.deactivateDocumentCreation.nameList` set to `true` deactivates this feature site-wide.
PDAC-1277	Template Support for Wiki Link Label and Tooltip	Support using templates for label and tooltip of the Wiki Link Macro.
PDAC-1296	Support adjust-title-on-parent for Doctype Wizards	Control whether or not the title of a document has the parent title as suffix.
PDAC-1284	Term Link Macro	Provide a macro that makes linking to glossary items easier. This macro makes the interface of the Wiki Link Macro more easy to use.
PDAC-1282	Static and Dynamic Document Link Macros	Make the use of the Wiki Link Macro easier for the use case of linking to projectdoc documents. For static and dynamic links there should be a separate macro. These versions provide typical defaults for some parameters so that the user is not bothered selecting suitable values for them.
PDAC-1279	Provide Artificial Properties for E-Mail Property	For email properties we need to provide the normalized and the text version of a property. The properties are identified by name (e.g. Email).
PDAC-1278	Support artificial Text Values for Name List Macro	In case the Name List Macro uses a template to render properties from the referenced document, there is no way to use this property in queries to match with the document's name. For this use case we add the text value of the property (property name + '$') as artificial property. Note that searching is always on the Name value (not the text that is rendered based on the rendering template). This allows users to alter the rendering without updating the queries. In case the rendered text (based on the template) should be matched, refer to the text version of the property (property name + '$'). In case the name should be rendered using the Display Property Macro, also refer to the text version of the property (since the plain property name refers to the rendered property value as rendered with by the template). The new artificial property is only added for new documents. Therefore a reindex is required to add this property for existing documents.
PDAC-1275	Improve Merging Deep Linked Values	When a deep link is used, the referenced values from multiple documents may need to be merged. Currently this merge is quite crude. This improvement merges name lists more effectively and removes duplicate values.
PDAC-1297	Lower Case Mode for Wiki Link Macros	Add a new parameter to the Wiki Link Macro to render the label in lower case. This is especially useful for the English locale where the name of the document or term in the glossary may be rendered lower case in the body of a section.
PDAC-1292	Override Artificial Properties	Allow to override artificial properties. This is required to put full control over the naming of properties into the hands of the users. For instance: The artificial property URL points to the current page as an artificial property. This makes it impossible for users to design a doctype with the property URL. A reindex is required for documents that tried to override artificial properties prior to this version.
PDAC-1280	Template Support for Cite Macro Tooltip	The tooltip parameter should support placeholders to include property values from the referenced document.
PDAC-1290	Tooltips for Display Document Properties Macro	When rendering references to properties in a template, the tooltip for each link is determined by the referenced document, but should be determined by the document holding the property.
PDAC-1283	Templates for Tour Macro in Definition List Mode	When the tour macro is rendered as definition list, the template is not used. It works only for the table render mode.
PDAC-1302	Allow NBSP for Append Text	Since spaces are not allowed as macro parameter values, users should use a instead. This improvement replaces the with a single space (32).
PDAC-1295	Parent Name Update	The Parent Macro and the new feature of the Name List Macro (Parent Name) has difficulties updating property values in case the Title of the document is changed.
PDAC-1293	Name List Macro Single Value Workaround	Hide the button on the macro panel for the Name List Macro in case of the single value mode. This is just a workaround to hide the widget that currently does not work.
PDAC-1289	Allow new Doctype IDs for Autocomplete of Name List Macros	Authors may want to reference doctypes that do not or do not yet exist.
PDAC-1288	Autocomplete for Parent Doctype of the Parent Macro	The Parent Macro should provide autocompletion for the Parent Doctype Parameter.
PDAC-1287	Autocomplete for Doctype Parameter on Document Properties Marker Macro	Support selecting a doctype with Doctype parameter of the Document Properties Marker Macro. The parameter should support tagging so that users may specify a non-existing doctype identifier.
PDAC-1286	Autocomplete for Display Reference Macro Document Property	The parameter Property Name (Document) should support autocomplete.
PDAC-1299	Hint for Doctype IDs for Blueprint Key	The help text for the Blueprint Key parameter should provide a hint that the doctype identifier is sufficient to identify the blueprint.
PDAC-1298	NPE on Materialization	When materializing an empty value, a Null Pointer Exception is thrown. Since this is caught, the trouble seems to be limited.
PDAC-1291	Anchors for Glossary Items starting with a Digit	When rendering a link from a short or abbreviated form of a glossary item to the long form, the link does not work in case the term starts with a digit. The issue is based on the HTML specification which does not allow identifiers to start with a digit. If this is the case and we construct our IDs for the glossary, we need to check if the raw name starts with a digit and adjust the generated ID accordingly.
PDAC-1285	Scroll PDF Export with transcluded Documents	When creating a PDF document with the Scroll PDF Exporter, the output type gets lost in case of transclusions. Therefore the printer configuration is not fully supported, rendering transclusion boxes although they should be suppressed.
PDAC-1281	Remove Duplicates from Name Autocomplete	Autocomplete for names should not show duplicates. Basically only the name is selected from the list and the name does not provide any more information. Showing duplicates in the list does not support any use case.

27 issues

Related Releases

Doctype Add-ons

The following doctype add-ons are recommended to be updated for the projectdoc Toolbox.

Doctype Add-on	Version
Core Doctypes Add-on	14.1.0
Doctypes for Agile Planning	11.1.2
projectdoc Developer Diaries	12.0.1
Doctypes for Project Management	5.1.2
Doctypes for Service Management	3.3.0
Doctypes for Business Strategy	3.1.1
Doctypes for Software Development	11.2.0
Doctypes for Teamwork	3.1.2
Doctypes for V-Modell XT	3.1.1

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	Status	Resolution	Description
PDCORED-267	Cycle and Cycle Phase	Done	Fixed	Add doctypes to define cycles, such as lifecycles or iterations.
PDCORED-271	Category Name Improvement	Done	Fixed	The category name is constructed from the parent's name and its short name. The string " / " is used as a separator. The separator should provide the space char dependent on the value of the parent and short name.
PDCORED-268	Parent Property Metadata Non-Defaults	Done	Fixed	On creating metadata the Parent Property is always set to the default and does not respect the macro parameter parent-property. Requires the projectdoc Toolbox 4.6.
PDCORED-270	Where Clause for Experience Level	Done	Fixed	The where clause needs to be corrected.

4 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-86	Parent Property Metadata Non-Defaults			Done	Fixed	On creating metadata the Parent Property is always set to the default and does not respect the macro parameter parent-property. Requires the projectdoc Toolbox 4.6.

1 issue

projectdoc Developer Diaries

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

Key	Summary	T	P	Status	Resolution	Description
DEVDIARY-128	Parent Property Metadata Non-Defaults			Done	Fixed	On creating metadata the Parent Property is always set to the default and does not respect the macro parameter parent-property. Requires the projectdoc Toolbox 4.6.

1 issue

Doctypes for Project Management

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

Key	Summary	T	P	Status	Resolution	Description
PDPRJMGMT-70	Parent Property Metadata Non-Defaults			Done	Fixed	On creating metadata the Parent Property is always set to the default and does not respect the macro parameter parent-property. Requires the projectdoc Toolbox 4.6.

1 issue

Doctypes for Service Management

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

Key	Summary	Status	Resolution	Description
SERVICES-20	Lifecycle Phase Defaults	Done	Fixed	Support adding Lifecycle Phase Documents as children to Lifecycle documents. A child automatically references the parent as its lifecycle if the parent is a Lifecycle document. Requires projectdoc Toolbox 4.6.
SERVICES-23	Lifecycle and Lifecycle Phase Update	Done	Fixed	Align the design to the Cycle and Cycle Phase provided by the Core Doctypes. This update includes links from the Lifecycle to its local Lifecycle Phases.
SERVICES-22	Parent Property Metadata Non-Defaults	Done	Fixed	On creating metadata the Parent Property is always set to the default and does not respect the macro parameter parent-property. Requires the projectdoc Toolbox 4.6.
SERVICES-21	Fix Element Section Title (DE)	Done	Fixed	Fix the DE version of the Element Section Title on the Lifecycle Phase Doctype. Items needs to be translated to Elemente.

4 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-17	Parent Property Metadata Non-Defaults			Done	Fixed	On creating metadata the Parent Property is always set to the default and does not respect the macro parameter parent-property. Requires the projectdoc Toolbox 4.6.

1 issue

Doctypes for Software Development

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

Key	Summary	Status	Resolution	Description
PDSWDEVD-142	Datatype Doctype	Done	Fixed	Provide a doctype to describe the data type of a property or code.
PDSWDEVD-145	Provide Version Information for Component	Done	Fixed	Allow to specify version information (since, deprecated, until) for the Component Doctype.
PDSWDEVD-143	Use Codes for Value Range	Done	Fixed	Using the code doctype for values of the range allows to document each value with a Code doctype instance.
PDSWDEVD-146	Center Short Type on Component	Done	Fixed	Center the column showing the short data type on the Component doctype template. The tables are part of sections.
PDSWDEVD-144	Short Data Type Default	Done	Fixed	For Property and Code Doctype the Short Data Type should render the short name of the referenced Data Type document.
PDSWDEVD-147	Parent Property Metadata Non-Defaults	Done	Fixed	On creating metadata the Parent Property is always set to the default and does not respect the macro parameter parent-property. Requires the projectdoc Toolbox 4.6.
PDSWDEVD-141	Typos in Interface Doctype (DE)	Done	Fixed	In section Semantics and Technical Infrastructure.

7 issues

Doctypes for Teamwork

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

Key	Summary	T	P	Status	Resolution	Description
PDTEAMWORK-25	Parent Property Metadata Non-Defaults			Done	Fixed	On creating metadata the Parent Property is always set to the default and does not respect the macro parameter parent-property. Requires the projectdoc Toolbox 4.6.

1 issue

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-25	Parent Property Metadata Non-Defaults			Done	Fixed	On creating metadata the Parent Property is always set to the default and does not respect the macro parameter parent-property. Requires the projectdoc Toolbox 4.6.

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.

projectdoc Toolbox 4.6 Release Notes

New and Noteworthy

Easier Linking

Autolinking on Document Creation

Create Links

Template Support for Labels and Tooltips

Enhancements to Autocomplete

Enhancements to Artificial Properties

Enhancements to Deep Links

Installation Instructions

List of Changes

Related Releases

Doctype Add-ons

Core Doctypes

Doctypes for Agile Planning

projectdoc Developer Diaries

Doctypes for Project Management

Doctypes for Service Management

Doctypes for Business Strategy

Doctypes for Software Development

Doctypes for Teamwork

Doctypes for V-Modell XT

Resources