Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Document Properties Marker
overridefalse
Short DescriptionA 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.
Doctypetopichide
NameChanging Names
Short Name
Parent
Parent Property
property-nameName
hide
Audience

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


Subject

Name List
doctypesubject
propertySubject


Categories

Name List
doctypecategory
names/ projectdoc / Features / Autocomplete
property-restrict-value-rangetrue
propertyCategories


Tags

Tag List
namesprojectdoc Toolbox, Confluence, REST, API, Web API Extension
propertyTags

hide
Flagshide
Iteration

Iteration
valueproduction

hide
Type

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


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

Expected Duration
Sponsors
Name List
doctypestakeholder
render-no-hits-as-blanktrue
propertySponsors

Sort Keyhide
projectdoc-section
Section
show-titleDescriptionfalse
Summary
titletitleDescription
This short tip shows how to change property values for a selection of documents. The approach is especially useful if a name of a document is changed and authors need to adjust all referencing documents accordingly.
Section
titlePrerequisites

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.

Note Box
titleNo API Documentation? Seriously?

I case you ask yourself: why is there no documentation for the REST API? WTF?

The REST API Browser has a bug. Therefore we need to decide whether we deploy a REST API that cannot be used via the add-on or provide a functional REST API, but without documentation.

Sounds strange? You may vote on CONFSERVER-57887 for solving this problem!

In case you need more information on this issue, please head for our blog post Problems with the Web API and the REST API Browser.

...

Section
titleWalk me through!

Since we use the strategy to show names only if the document is in Released, Production, or Deprecated state, we now recognized how lax we handled the Iteration state of documents in our documentation.

Here is an example on how we moved the iteration of all our role documents to Production.

Steps
Section
titleOpen REST Service in REST Browser
  1. Log in as admin
  2. Click i the cog (right side of the menu bar) for Confluence administration and click on General configuration
  3. Select REST API Browser from the left menu
  4. Type projectdoc in the input field on the left upper side and unselect Show only public API

  5. Select projectdoc/1/document from the services listed on the left
Section
titleSelect the Documents

To select the documents to apply the changes to, we need to find all documents in a state prior to "Released" and want to change their Iteration value to "Production".

This is the Where Clause to select these documents of doctype role: $<Doctype>=[role] && $<Iteration>~(Facade, Filled, Focused, Finished)

Check that every listed document is correctly part of the result set. If not adjust you Where Clause accordingly. If everything is correct, copy the value of id-list.

This is the list of page IDs that match your result set. Copy the values without the quote characters Make sure that you do not miss any digits (i.e. from the first or last page ID).

Section
titleApply changes

Now switch to the PATCH tab.

Add the list of page IDs from the last step to the id-list parameter.

Image RemovedImage Added

Add the following information to patch the list of documents.

Code Block
languagejs
{
   "property": [
     {
       "name": "Iteration",
       "value": "<ac:structured-macro ac:name=\"projectdoc-iteration\"><ac:parameter ac:name=\"value\">production</ac:parameter></ac:structured-macro>",
       "controls": "hide",
       "position": "replace"
     }
   ]
 }

This JSON document will replace the value of the Iteration property on each document referenced in the id-list.

Transclusion
document@self
idsBackup your data!

If you have a recent backup and checked this on a test environment, then click Send.

The response will contain a list of results changing the documents.

Section
titleSummary

We have shown some use cases for the demand of changing values for a collection of projectdoc documents.

It requires manual steps that need to be conducted very carefully. It is strongly recommended that you have a recent backup in case your calls corrupt pages in your Confluence instance.

In the future we will probably provide tools to make this task easier. In the meanwhile authors have tools to at least allow these task to be run effectively.

Section
ignore-template-buttonstrue
titleSubordinate Topics
Hide From Reader

Create from template
blueprintModuleCompleteKeyde.smartics.atlassian.confluence.smartics-projectdoc-confluence-space-core:projectdoc-blueprint-doctype-topic
buttonLabelCreate Topic

Display Table
doctypetopic
render-no-hits-as-blanktrue
render-modedefinition
selectName, Short Description
restrict-to-immediate-childrentrue
sort-bySort Key, Name

...