Dynamic Property Values

Versions Compared

Old Version 7

changes.mady.by.user Robert Reiner

Saved on 24. Aug 2022

compared with

New Version Current

changes.mady.by.user Robert Reiner

Saved on 20. Jan 2023

Key

This line was added.
This line was removed.
Formatting was changed.

...

Document Properties Marker

doctype	topic
override	false

Short Description

Property values should only change when a document is saved. They should not be dependent on request-time. If they are, then they are called 'dynamic'.

Name

Dynamic Property Values

hide

Short Name

hide

Parent

Parent Property

property-name	Name

hide

Audience

Name List

doctype	role
render-no-hits-as-blank	true
render-list-as-comma-separated-values	true
names	Author, Documentation Gardener, Documentation Architect
property-restrict-value-range	true
property	Audience

empty-as-none

true

Subject

Name List

doctype	subject
property	Subject

Sponsors

Name List

doctype	stakeholder,organization,person,role
render-no-hits-as-blank	true
property	Sponsors

Since

6.0

Sort Key

hide

Section

show-title	false
title	Description

The concept of dynamic property values should be mastered by users right from the start.

Using dynamic property values with the projectdoc Toolbox seems quite natural. Especially novice users may not be aware of the issues that come with them.

This short article explains the problem with dynamic property values and shows use cases to handle them.

The information is based on the projectdoc Toolbox version 6.0.

projectdoc-section

title	Summary

Section

title	Prerequisites

...

Section

title	Problem Description

When a user edits a document, only one document at a time is changed. Multiple users my edit multiple documents at the same time, but for the system most of the documents stay the same, only a number of them is altered.

A document may use values from other documents. This is the case if for excample example the Tags Property is referencing tags. It uses the name of the tag documents to render as values for the Tags Property. When a service document lists the systems it requires, then the service document uses the names and maybe further properties of the system documents, to render the values of its properties.

When only one document is changed, the property values of all other documents are calculated and readily available.

When all projectdoc documents are erased, they can be rebuilt from scratch, since all information is actually derived from Confluence pages. Some information architectures that seemed sound when used in the one-document-at-a-time context will now show if they can cope with the from-scratch context.

One issue may be with circular references as property values. References should be pointing in one direction. The projectdoc Toolbox will report circular references accordingly. Sometimes those circular reference first show up in the from-scratch scenario. That is because a value may be available from a existing document, but not if the document needs to be calculated.

Note Box

title	Property Value versus Document Body

The document body is the part of a Confluence page that contains all the sections.

References in the body of a document are no problem. This is because they are always rendered at request-time, never stored in Lucene or in a cache.

Therefore the rendered text in bodies of those documents cannot be found in searches.

Another issue are dynamic properties. This may be more dramatic than circular references. Users may experience dynamic property issues even in the one-document-at-a-time context. The property values of such documents may often be considered as as not up-to-date.

...

Section

title	Definition

The value of a dynamic property is dependent on the request-time.

Typically property values must be rendered at the time a page is stored and must not change due to external events. A property may reference another property. If a referenced property changes, the document with the reference is informed and the property value is updated accordingly. Changes only happen when a document is stored. A dynamic value does not reference another property value, but builds result sets at request-time based on queries or fetches information from other resources then projectdoc documents. The update mechanism is not applied to dynamic values, therefore dynamic values represent the value at the time they where stored. This is most likely an out-of-date value.

However there are use cases, where dynamic property values can be a valid solution. But special considerations need to be made: the property should probably not be indexed (

Static Document Link

document	noindex

) and always be rendered at request-time (in other words: not be cached,

Static Document Link

document	no-render-cache

). Or it may not even be considered to be a property at all (

Static Document Link

document	no-property

, available since version 56.20).

Section

title	Modes

The mode to handle dynamic properties is defined by the system property de.smartics.projectdoc.dynamicValues. This is currently considered an experimental feature.the administrator via the configuration screen

Static Document Link

document	Dynamic Property Value Handling

The following modes are available with the projectdoc Toolbox with version 56.2.0.

Content Marker

id	table-of-modes

Mode	Description

allow

off

No restriction. Not recommended.

This mode is used for backward compatibility.

allow

Restriction only to use macros that are not designed to be used as a property value. For instance using a properties table or a wiki link macro.

Dynamic values are allowed. Users are responsible to use them correctly.

This mode is used for backward compatibility.

lenient

Dynamic values are allowed, and if proper

control

controls are not set,

then

Static Document Link

document	no-property

is assumed.

The following controls are considered proper:

Static Document Link
document noindex
Static Document Link
document no-render-cache
Static Document Link
document no-property
Static Document Link
document force-property

Health checks will signal the use of deprecated features of macros considered to be dynamic.

This mode may be selected to allow users to use dynamic values.

strict

Dynamic values are allowed

, and

if proper

control

controls are

not

set

, then

Static Document Link

document	no-property

is assumed

The following controls are considered proper:

Static Document Link
document noindex
Static Document Link
document no-render-cache
Static Document Link
document no-property

This mode will be the default mode for the next major version of the projectdoc Toolbox. It is the recommended mode for new users.

explicit

Dynamic values are allowed, if proper controls are set:

Static Document Link
document noindex
Static Document Link
document no-render-cache
Static Document Link
document no-property
Static Document Link
document force-property

The implicit flagging of

Static Document Link

document	no-property

when a dynamic property is encountered, is not allowed.

This mode should only be used for testing the health of documents, not as a runtime mode.

block

No dynamic value is allowed.

This mode may be helpful to find all locations of dynamic values with a health check. Not recommended as a runtime mode.

Section

title	Health Service

Administrators may check the current status of the projectdoc documents by the use of the REST service projectdoc-internal/1/health/find-dynamic-values.

The service allows to check spaces with different modes.

For version 56.2 0 of the projectdoc Toolbox the default mode is allow for compatibility reasons. For new users a value of strict or lenient is recommended.

The interface of the health service shown in the REST API Browser Image Added

With the parameters additional-dynamic-macros and use-default-configuration, administrators may test configurations in addition and without the default configuration.

Section

title	Default Dynamic Value Configuration

The Default Dynamic Value Configuration Service (projectdoc-internal/1/health/default-dynamic-value-configuration) allows to retrieve the configuration that controls the default processing of property values. It is deactivated by setting the parameter use-default-configuration of the

In-Document Link

anchor	Health Service

to false. In the configuration to check the use of dynamic values at run-time the defaults are used per default (see

Static Document Link

document	Dynamic Property Value Handling

There are no parameters to this service. Image RemovedIt returns a list of the dynamic macro checks. Each check is reported in the following format:

Code Block
{ "macroName": "<name-of-the-macro>", "paramChecks": [ { "problematicParamName": "<name-of-a-macro-parameter", "specificDynamicValueCheck": { "id": "<identifier-of-the-type-of-check" } } ] }

The listed macroName identifies the macro that is check. If a macro is not part of the returned list, it is not considered to be checked and is considered safe to use as a property value by default.

Note Box

The default configuration is only checking on projectdoc macros. If you are using macros of third-party apps as property values, you need to add those to your configuration when running the

In-Document Link

anchor	Health Service

Some macros may be dynamic no matter what parameters are used. But some macros may be safe to use a property values, if and only if specific parameters or even specific parameter values are not used. For instance the

Static Document Link

document	Name List Macro

is safe to use as property value only if there is no search configured. In case the macro is safe but for a set of parameters, then the name is listed under problematicParamName (one entry in paramChecks per parameter name). How the parameter value is checked is determined by the specificDynamicValueCheck. Currently there are these type of checks provided (identified by the value of the id property):

Name Description

IsDynamicNoMatterWhat

If the parameter is specified with any non-empty value, then the macro is considered to be dynamic and must not be used as a property value.

This check is also used for macros that are not considered dynamic per se, but should nevertheless not be used as a property value.

This is used for macros that should never be used as property values.

AllowModeOnly

If the mode is allow, then no property is actually considered to be a dynamic value.

This is for backward compatibility. These macros should usually not be allowed, but may be allowed for the allow mode.

ModeSpecificControls

If there are proper controls on the value, then the value is not considered dynamic, even if it basically is.

So an author may check if the use of the macro is actually an issue in this context and if not use the proper control to allow its use. Which control is allowed to make a macro pass as property value is defined by the mode selected by the administration.

Why can the use of the macro be no problem in some cases? If the search is using values from a delegate space and these values are never changing, then the use may be okay. This includes that if the value actually does change or the projectdoc caches are cleared, then proper measurements need to be taken to update the caches (for instance run a refresh on the delegate space first).

Section

title	Health Logger

Administrators may use the health logger de.smartics.projectdoc.healthCheck.dynamicValues for more logging output.

See

Static Document Link

document	Logging

for more information on loggers.

...

Section

title	Resources
intro-text	More information on this topic is available by the following resources.

Tour

render-no-hits-as-blank	true
render-as-definition-list	true
marker-column-property-name	Title
replace-title-with-name	true

Title	Short Description
No dynamic Property Values
no-property
force-property
noindex
no-render-cache
Dynamic Property Value Handling

Space shortcuts

Page tree

Docs

Support

Free Blueprints

Tooling for Blueprints

Free Extensions

Spaces

Plugins for Maven

Incubator

Libraries for Java

Incubator

Add-ons for Confluence

Tools

Support

Team

Legal

Versions Compared

Old Version 7

New Version Current

Key

About

Keep up-to-date!

Powered by