- Created by Robert Reiner, last modified on 16. Feb 2021
Send-to-Homepage, Remote Controlled Documents, Deep Links in Queries, Authentication for Remote Information Systems, List Queries, Enhanced Recursion Detection, and model-based Core Add-on
Today we released version 2.0.0 of the projectdoc Toolbox on the Atlassian Marketplace!
The major release signals that all related doctype and extension add-ons need to be updated. We will continue with this semantic versioning from this version on.
IMPORTANT: Add-on Update and Reindex required!!!
Please note that this new version of the projectdoc Toolbox requires all doctype and extension add-ons for projectdoc need to be updated! See Required Add-on Updates for version details.
Also very important: The site needs to be reindexed! Otherwise exact match queries will fail (that is: find no documents). For some more information see Reindex required on this page.
The projectdoc Toolbox is an add-on for Confluence supporting agile software development teams to collaborate on process, project, system, and product documentation.
If you want to learn more about the projectdoc Toolbox and how it helps to create good project documentation, please refer to the introduction video!
The following image is a link to a video on YouTube. When you click the link your browser will serve a page from youtube.com
.
Very interesting, but way too fast?
Step through at your own pace with with our Prezi Presentation (external link to prezi.com
)!
In the Online Manual you’ll find additional video material that introduces you in the concepts of the projectdoc Toolbox.
Refer to use cases and show cases for information on how to use the projectdoc Toolbox.
New and Noteworthy
The following changes may be the most interesting of this release.
Exact Match Query Fix
Exact match queries failed to be exact for word stems. That is in an exact match for "Tree" documents having "Trees" where also a match.
This has been fixed with this version. Unfortunately that requires that all exact match tokens need to be recalculated. Therefore a reindex of all pages of the Confluence site is required and the document cache needs to be cleared.
How do I reindex projectdoc Documents?
Run the content reindexer.
Troubleshooting Reindexer for projectdoc Documents provides an instruction on how to run the process.
Send to Homepage
Most projectdoc blueprint witzards allow to send a new page to its configured homepage. This feature has been completely redesigned which allows to render the altered location already in the page editor.
The update will also fix an issue where sending the new page to another space has been broken with the latest versions of Confluence.
See PDAC-776 - Getting issue details... STATUS .
Remote Controlled Documents
The projectdoc Toolbox supports use cases where a remote system defines the content of a page. The macro parameters of the following macros can be controlled by request parameters.
- Transclusion Macro
- Transclude Documents Macro
- Display Table Macro
- Tour-by-Property Macro
- Index Entries Table Macro
An application may configure the rendering of a page via request parameters. Each macro can be addressed by its manually defined identifier (which happens to be rendered as a HTML identifier attribute). This allows to combine information in Confluence at request time.
Use cases are applications that need to render information on Confluence dependent on the context of the application. If the page needs to show information of different types, remote controlled documents allow to not materialize each combination of this information. Instead the different types are selected with request parameters.
Deep Links in Queries
Prior to this version projectdoc macros had access to the properties of documents in the result set. With version 2.0 also properties of referenced can be accessed. This feature is called "Deep Links".
Suppose "Document
" is a property that has a reference (created by a projectdoc macro or a Confluence link) to another document. To select the name of the document, use "Document->Name
" as expression of the select macro parameter. Links may be deeper than one level (e.g. " Document->Ref->Person->Name
").
The following macros support this feature:
- Display Table Macro
- Transclude Documents Macro
- Display List Macro
- Display List Template Macro
- Tour Macro
- Display Document Properties Macro
This feature is considered experimental. More information on Deep Links for Select Clauses and Where Clauses.
Impersonating OAuth and Basic Authentication
The projectdoc Toolbox provides services for the Information Systems Extension that allows to use Application Links to authenticate. Impersonating OAuth and Basic Authentication are supported.
The autoconverter (fetching the title information from a remote HTML page) and the transclusion macros take advantage of this new feature.
Breadcrumbs
projectdoc allows to provide a document name in addition to a page title. The page title is required to be unique within a Confluence space, but the name does not. It should be unique within its doctype, but even this constraint is not enforced.
The new breadcrumbs macro (see PDAC-776 - Getting issue details... STATUS ) allows to render the name instead of the title on the breadcrumbs. This macro is required to be rendered in the pages context. We use Brikit to provided this service for the header of every our pages.
Transaction Problems
In certain environments users suffered from transaction problems. These have been fixed in projectdoc Toolbox 1.17.1 Release Notes and are also available in this release.
Users that have faced transaction problems in the past are encouraged to test this version with their test cases!
List Queries
The projectdoc Toolbox allows to specify list queries in a more compact form due to PDAC-802 - Getting issue details... STATUS .
Please check the reference (ids=List Query Examples / tags=) to the document 'Search Tips' to transclude from.
If you want to silence this message on missing content, check 'Missing Content Message'.
Please refer to the Transclusion Macro documentation for more information about this macro.
Enhanced Recursion Detection
This version puts more effort in detecting recursions between documents via property references. This is typically only an issue on an empty document cache. But in case of an empty cache this detection stops recursive calls quickly.
Doctype Models
With the Doctype Maven Plugin we unify our blueprint configuration. This will allow us to apply changes to doctypes faster.
Currently the Core Doctypes have already been updated. New doctype add-ons will be based on models and the other existing ones will be translated one-by-one.
Due to the new model approach, we also updated some of the internationalization keys. Therefore old doctype add-ons will not work with this version of the projectdoc Toolbox.
Import Version via REST
The latest version of the Maven Extension provides a REST resource to import version information from a Maven artifact. This allows to integrate the import of version information from a build server automatically.
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!
Doctype Add-ons
Doctype add-ons provide space and page blueprints based on the projectdoc Toolbox.
projectdoc Core Doctypes
List of breaking changes in this add-on.
projectdoc for Software Development
List of breaking changes in this add-on.
projectdoc Add-on for arc42
List of breaking changes in this add-on.
projectdoc for Agile Planning
List of breaking changes in this add-on.
projectdoc Developer Diaries
List of breaking changes in this add-on.
projectdoc for Java Developers
List of breaking changes in this add-on.
projectdoc for Maven Developers
List of breaking changes in this add-on.
Doctypes for Project Management
List of breaking changes in this add-on.
Extension Add-ons
Extension add-ons extends the functionality of the projectdoc Toolbox.
Bookmarklets Extension
List of breaking changes in this add-on.
Information Systems Extension
List of breaking changes in this add-on.
Maven Extension
List of breaking changes in this add-on.
Web API Extension
List of breaking changes in this add-on.
Known Issues
This release has the following issues.
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.
Everything optional
Note that all doctype add-ons and extensions are optional. None is required to be installed to run the projectdoc Toolbox. Although the use of the Core Doctypes is recommended.
Reindex required
The following changes require a content reindex.
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.
projectdoc for Software Development
List of changes in this add-on.
projectdoc Add-on for arc42
List of changes in this add-on.
projectdoc for Agile Planning
List of changes in this add-on.
projectdoc Developer Diaries
List of changes in this add-on.
projectdoc for Java Developers
List of changes in this add-on.
projectdoc for Maven Developers
List of changes in this add-on.
Doctypes for Project Management
List of changes in this add-on.
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.
Bookmarklets Extension
List of changes in this add-on.
Information Systems Extension
List of changes in this add-on.
Maven Extension
List of changes in this add-on.
Web API Extension
List of changes in this add-on.
Resources
- Release Notes for the projectdoc Toolbox
- Information on all released versions of the projectdoc Toolbox for Confluence.
- Glossary
- Terms used in and defined for projectdoc.
- FAQs
- Questions and answers related to the projectdoc Toolbox and Confluence.