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.

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 other 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.

The upgrade is part of the update of the projectdoc Toolbox

Guided by the tables of the last version, the upgrade process will populate the new tables. This is different to a rebuild that starts on completely empty tables. If the tables are empty, the process needs to traverse all pages of all spaces in its search for projectdoc documents. Since this is not the case for the upgrade, the upgrade process is typically quicker than the rebuild process.

For more information see section 

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 programaticallyprogrammatically.

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 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.