Versions Compared

Key

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

...

Document Properties Marker
doctypetopic
overridefalse


Short DescriptionProperty 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'.
NameDynamic Property Valueshide
Short Namehide
Parent
Parent Property
property-nameName
hide
Audience

Name List
doctyperole
render-no-hits-as-blanktrue
namesAuthor, Documentation Gardener, Documentation Architect
property-restrict-value-rangetrue
propertyAudience
empty-as-nonetrue


Subject
Name List
doctypesubject
propertySubject

Categories
Name List
doctypecategory
property-restrict-value-rangetrue
propertyCategories

Tags
Tag List
propertyTags

Flagshide
Iteration

Iteration
valuefocused

hide
Type

Name List
doctypetopic-type
render-no-hits-as-blanktrue
namesTutorial
property-restrict-value-rangetrue
propertyType


Level of Experience

Name List
doctypeexperience-level
render-no-hits-as-blanktrue
namesNovice
propertyLevel of Experience


Expected Duration
Sponsors
Name List
doctypestakeholder,organization,person,role
render-no-hits-as-blanktrue
propertySponsors

Sort Keyhide


...

Section
show-titlefalse
titleDescription

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.


Section
titleSummary


Section
titlePrerequisites


Section
titleProblem Description

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, only a number of them is altered..

A document may use values from other documents. This is the case if for excample 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 If all projectdoc documents are erased, they can be built 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 that with circular 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. That is because a value may be available from a existing document, but not if the document needs to be calculated.

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, if documents seem to be stale, also known . The property values of such documents may often be considered as as not up-to-date. 


Section
titleSummary
Section
titlePrerequisites
Section
titleDefinition

The value of a dynamic property that is dynamic is dependent on the rendering 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 information 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 documentdocuments. The update mechanism is not applied to dynamic values, therefore dynamic values represent the value at the time they where stored and this probably . This is most likely an out-of-date value is rendered at request time.

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

Static Document Link
documentnoindex
) and always be rendered at request-time (in other words: not be cached,
Static Document Link
documentno-render-cache
). Or it may not even be considered to be a property at all (
Static Document Link
documentno-property
, available since version 5.2).


Section
titleModes

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.

ModeDescription
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 

Static Document Link
documentno-property
is assumed.

The following controls are considered proper:

  • Static Document Link
    documentnoindex
  • Static Document Link
    documentno-render-cache
  • Static Document Link
    documentno-property
  • Static Document Link
    documentforce-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 are not set, then 

Static Document Link
documentno-property
is assumed.

The following controls are considered proper:

  • Static Document Link
    documentnoindex
  • Static Document Link
    documentno-render-cache
  • Static Document Link
    documentno-property

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:

  • Static Document Link
    documentnoindex
  • Static Document Link
    documentno-render-cache
  • Static Document Link
    documentno-property
  • Static Document Link
    documentforce-property

The implicit flagging of 

Static Document Link
documentno-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.


...