You are viewing an old version of this page. View the current version.
Compare with Current
View Page History
« Previous
Version 2
Next »
A name in projectdoc used to identify a document is not considered a hard reference. When changing the name of a particular document, the references to the original name do not automatically change. This is by design. It may also by the cause of annoyance. This tip provides information how to deal with this.
Prerequisites
Besides the projectdoc Toolbox installed on your Confluence server, the Web API Extension also needs to be installed. You may use the Web API via any REST client. This tip assumes that you have installed the REST API Browser.
Identifying Documents
The projectdoc Toolbox defines the concept of a projectdoc Document. Such a document is a Confluence Page with properties and sections.
A projectdoc Document can be identified either by its title and space or its name and doctype.
Title and Space Key
By design a page on a Confluence server is uniquely identified by its title and space key.
Authors can take advantage of this when they need to reference a page. In case the title is renamed, all links are also adjusted. This way all references still hold after the rename action.
References to document with links can be made with
Such a link is considered to be a hard reference. The link is tightly connected to the page.
Name and Doctype
The name and doctype of a document also identifies a document. But not necessarily uniquely. It is good practice – that can be naturally followed most of the time – to keep the name unique for each doctype. This is not enforced, though.
References to documents with names can be made with
Such a link is considered to be a soft reference. The macros take the specified name and doctype literally. In case the document actually exists, a reference is rendered. If the document goes away (either by deletion, by changing the privileges, or by renaming), then name, as a string literal, is not changed. This way the document having the Name List Macro with a name as its value, is still be found by this property value (e.g. by a search or by a query conducted by a Display Table Macro).
This of the name list as a couple of advantages. In case authors remove a doctype homepage, references to that homepage will automatically reference the homepage in a related space. In case authors import pages to another Confluence instance, the references will immediately render as links to existing documents.
When a name is wrong ...
In case authors actually need to change a name, this change cannot be by design an instant one. We are considering to include options to make the adjustment automatically in the future. Maybe by a dialog which will ask whether or not to change the names in referencing properties. This is similar to the action of deleting a page and asking whether or not the children should be removed, too.
In the meantime this is a manual step. In case there is more than a couple of pages is involved, authors should consider to use the Web API to do the job.
Walk me through!
Here is an example on how we moved the iteration of all our role documents to Production.
