projectdoc Toolbox

Show how to import properties from other projectdoc documents into a projectdoc document.

Audience: Documentation Architect, Documentation Gardener, Template Author, Author
Type: Tip
Level of Experience: Expert

Contents

For modular documentation it is important to wrap pieces of information in a cohesive and coherent way. Keep information that belongs together at one place and make it identifiable with clear boundaries to other pieces of information.

One use case in IT service management (ITSM). To define services or systems you may need to define configuration options. These options could be implemented as properties on the projectdoc document for a specific service or system. But this has two drawbacks:

The configuration options are intermingled with other service/system properties, like service level agreement (SLA) information
The configuration options cannot be referenced by themselves

To provide a solution for use cases where changes to properties of one document is automatically updating importing documents, the new Document Properties Supplier From Documents Macro has been added. This macro allows to define a configuration document for the ITSM use case and to imports theses properties to a service or system. Changes to the configuration are automatically updating the service or system document. This tip shows how to do this.

Use Case

Prior to projectdoc Toolbox for Confluence version 2.3 users could employ the Document Properties Supplier Macro to add additional properties to a projectdoc document. This made it easier for the author and reader to identify properties that belong together. In prior versions these properties could also be defined in a separate document, but they had to be imported individually by name. In case the name changed, a property has been removed or added, all service and system documents needed to be updated according to this change.

The tip Import Properties for Transclusion shows how to implement these use case.

There is also an option to import properties from an attached properties file.

The simplified use case demands to document a configuration with two properties. This configuration is used by a system. The configuration can be referenced by its own. If the system is queried for configuration properties, it answers with the properties imported from the configuration.

Once a property is updated in the configuration, the update is propagated to the system. Therefore configuration requests directed to the system will always return the updated version of the property.

Create the Configuration Document

For simplicity of this tutorial we assume no specific template to document a configuration.

We add the following properties to the Document Properties Marker Macro on the top of the projectdoc document. For this short tutorial this document is named "Web Configuration".

Note that we specify the property control supply in the last column. This is required to make the property available for import by other documents.

Create the Service Document

The service should now import all supplied properties from the configuration document.

There are two ways to do this.

Direct Reference to Document

First the simpler version. Reference the Web Configuration document.

Once saved the Document Properties Supplier From Documents Macro will render in the Section Macro like this:

If the required heap memory is updated to 8 GB, the change is immediately seen once the web service document is rendered.

Reference via Property

The second option is to add a property to the web service document to reference the configuration. This option is typically useful for template authors. The can add the supplier macro to a section and page authors can provide the additional properties simply by adding a link as a property value.

If the Documents parameter is empty, the current document is referenced. The Properties parameter points to the property named Web Configuration Reference in the current document.

Make sure that all properties and sections have unique names. If the name of a property and a section are the same, they cannot be referenced individually. For instance if the property and the section were named "Web Configuration" you cannot select them by the use of the Display Table Macro.

Again, the service is rendered like this.

If you do not want the property to be shown, add the hide control to the Web Configuration Property.

Summary

With the new Document Properties Supplier From Documents Macro it is now even easier for users of the projectdoc Toolbox (version 3.2 and later) to create modular documentation and import properties from other projectdoc documents.

This tip has shown how to create a document with properties and import it into another document.

References

Document Properties Supplier From Documents Macro: Import properties from another projectdoc document.
Import Properties for Transclusion: Shows how to import properties from another document to be applied to placeholders in transclusions.
supply: Marks a property as importable by other projectdoc documents.
supplied: Marks a property as being imported from another projectdoc document.
unsupplied: Marks a property as being imported from another projectdoc document, but its supplied status overridden by a local configuration.

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