You are viewing an old version of this page. View the current version.
Compare with Current
View Page History
« Previous
Version 5
Next »
Information for administrators on how to rebuild projectdoc documents from scratch or start a reindex process.
The projectdoc Toolbox extracts information from Confluence pages to form projecdoc documents. These documents are stored in index structures to ensure a quick lookup of document property information.
While the projectdoc Toolbox uses the Lucene Index to make lookups, it also needs its own lookup tables to be up-to-date.
This document provides information on the use cases of the rebuild and refresh processes.
Prerequisites
The rebuild processes are available since version 5.0 of the projectdoc Toolbox. Prior to this version the projectdoc Toolbox provided indexing services that run on a different traversal strategy. The new processes allow to usually perform more quickly.
We will use the term 'update' to generally refer to either reindex, rebuild, refresh, revalidate, and repair processes. We reserve the term reindex for the content indexing with Lucene. The term indexing refers to the update processes being available prior to version 5.0. The terms reindex, rebuild, refresh, revalidate, and repair are explained in this document.
Kinds of Updates
The projectdoc Toolbox knows four kinds of updates to be performed for projectdoc documents.
| Update | Description |
|---|
| Refresh | Recalculate document properties of all projectdoc documents. Refresh is the fastest update task. Only confluence documents which are known to be projectdoc documents will be handled. |
| Revalidate | Recalculates document properties for all invalid projectdoc documents. This is rarely necessary since invalid pages get revalidated on page access. |
| Repair | Recalculates document properties for all projectdoc documents with a lower version number than their Confluence pages. This should be rarely necessary because the document properties are updated on an update of the Confluence page. This process helps to find and correct information of pages where the update failed. |
| Rebuild | Clears the projectdoc document tables and iterates over all pages on the Confluence server. This should never be done without proper reason because it takes an enormous amount of processing time. If you think your Lucene reindex takes a lot of time, try this one. It is probably 10 times slower. |
If everything works fine with the projectdoc Toolbox none of these services are required. Typically all lookup information is up-to-date. An update is made whenever a projectdoc document is updated by a user.
Refresh
One use case for refresh may appear after the installation of an projectdoc Toolbox update. The new version may add new artificial properties or update the information stored in artificial properties. In this case a refresh is required to update the information for all existing projectdoc documents. New documents or existing documents that have been manually updated will provide the additional or updated document properties.
If the update of a document failed, because events did not get properly process, either due to system problems or issues with the software, a refresh may also be necessary to bring the documents back to the up-to-date state.
Revalidate
When a document needs to be updated, the projectdoc Toolbox may decide to only mark the document as out-of-date and proceed with the current process. The update will be postponed to a later time when the updated version of the document is actually required.
In typical use cases the updated document will immediately be read for rendering to the user who has updated the Confluence page. So this is usually a use case if the Confluence document was updated programmatically.
The advantage of this process is that administrators may decide the point in time at which a larger set of invalid documents should be revalidated so that this process is not executed just-in-time when a user requests the projectdoc document.
Administrators may have a look at the invalid flag on a projectdoc document to check the amount of invalid documents.
Repair
Repair is required if a projectdoc document is not in-sync with its Confluence page. Being not in-sync is determined by checking the version information, which is an integer value. If the version number of the projectdoc document is smaller than that of the Confluence page then this projectdoc document is deemed not in-sync.
Rebuild
All projectdoc document information is derived from the source code of the corresponding Confluence page. So if the lookup tables are cleared this information may be recalculated.
Unfortunately this may be a very time consuming process. Not only does the process need to recalculate each projectdoc document, it may also need to recalculate a document multiple times. This is because a property value may depend one or more property values of other documents which in turn may depend on property values of orther documents and so forth. The more complex the web of information is, the longer the process will take.
It is highly recommended to check this use case on a test installation with the production data in advance. This way the administrators may communicate the duration of the rebuild to the users.
Kinds of Iteration
The duration of an update process is also dependent on how the documents to process are found.
As long as the projectdoc documents are all in the tables, the process may simply iterate over the document table and update each document accordingly.
If projectdoc documents are missing, then the Confluence pages must be traversed, which will take more time.
Administrators may decide to restrict the search for candidates to process by spaces. This is helpful for use cases where Administrators know in which spaces the projectdoc Toolbox is actually used.
Services may also be instructed to search only in spaces with a projectdoc homepage. This is helpful if users will either use projectdoc documents in a space or not and if they use them, all Confluence pages are projectdoc documents.
Admin User Interface
The Admin User Interface is a simplified interface to cover the typical use cases with preconfigured parameters.
If background processes start one of the update services, then this will be shown in the UI. Administrators may also access the underlying long-running task via the Confluence REST interface.
The UI is part of the General Configuration screen of Confluence for Administrators: Rebuild & Refresh
This UI provides access to all four use case: Refresh, Revalidate, Repair, and Rebuild.
In case administrators need to control the parameters, they need to use the underlying web services via their REST interface directly.
Upgrade Task
The upgrade task is applied automatically.
From pre 5 to 5
The upgrade task "AO Table Migration 4->5" migrates the tables from its old structure version 4 to the new structure version 5. The name of the tables reflect this by adding a number after the intial "PD" (and the initial identifier of the plugin).
The description of the task is "Migrates the AO tables of version 4 of the projectdoc Toolbox to version 5."
