You are viewing an old version of this page. View the current version.
Compare with Current
View Page History
« Previous
Version 5
Next »
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'.
The concept of dynamic property values should be mastered by users right from the start.
When a user edits a document, only one document at a time is changed. Multiple users my edit multiple documents at nearly the same time, but for the system most of the documents stay the same, a number of them is altered.
If all projectdoc documents are erased, they can be built 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 from-scratch context.
One issue may be that references as property values go wild. 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. 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, if documents seem to be stale, also known as not up-to-date.
Definition
The value of a property that is dynamic is dependent on the rendering 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 information 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 document. The update mechanism is not applied to dynamic values, therefore dynamic values represent the value at the time they where stored and this probably out-of-date value is rendered at request time.
However there are use cases, where dynamic property values can be used. But special considerations need to be made: the property should probably not be indexed (noindex) and always be rendered at request time (in other words: not be cached, no-render-cache). Or it may not even be considered to be a property at all (no-property).
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 following modes are available with the projectdoc Toolbox with version 5.2.
| Mode | Description |
|---|
allow | No restriction. 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 are not set, then no-property is assumed. The following controls are considered proper: 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 are not set, then no-property is assumed. The following controls are considered proper: This mode will be the default mode for the next major version of the projectdoc Toolbox. |
explicit | Dynamic values are allowed, if proper controls are set: The implicit flagging of 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. |
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 5.2 of the projectdoc Toolbox the default mode is allow.
Health Logger
Administrators may use the health logger de.smartics.projectdoc.healthCheck.dynamicValues for more logging output.
See Logging for more information on loggers.
Resources
More information on this topic is available by the following resources.
