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.
Walk 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.
- Log in as admin
- Click i the cog (right side of the menu bar) for Confluence administration and click on General configuration
- Select REST API Browser from the left menu
- Type projectdoc in the input field on the left upper side and unselect Show only public API
- Select projectdoc/1/document from the services listed on the left
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).
Now switch to the PATCH tab.
Add the list of page IDs from the last step to the id-list parameter.
Add the following information to patch the list of documents.
{
"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"
}
]
}
Note that we replace the complete value, including the macro that holds the actual value of "Production". The value is the macro in the Confluence Storage Format.
This JSON document will replace the value of the Iteration property on each document referenced in the id-list.
Backup your data!
In case the Web API changes documents the wrong way, there is no way to get back easily. You may need to find the corrupted pages and restore the last valid version from history. Therefore we recommend strongly that you check your calls on a copy of your production system. Before running a call on the production system you must make sure that you have a current backup to roll back any corruption of your data the call may have caused.
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.
