projectdoc Toolbox

Space shortcuts

Page tree

Versions Compared

Old Version 9

changes.mady.by.user Robert Reiner

Saved on

compared with

New Version 10

changes.mady.by.user Robert Reiner

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Section
titleKinds of Maintenance

The projectdoc Toolbox knows seven kinds of maintenance processes to be performed for projectdoc documents. Two of them, update and repopulate, are currently not implemented and reserved for futher versions of this service.

If everything works fine with the projectdoc Toolbox and no upgrade is required due to a version change then 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.

Section
titleCentral Use Cases

For maintenance reasons an admin may need to do a refresh of the documents or builds all documents from scratch with a rebuild.

If an upgrade is required, it is part of an update of the projectdoc Toolbox app.

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

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.

Upgrade

Starts the installation of a new version of the projectdoc Toolbox that includes a special kind of rebuild.

Upgrade is always part of an update of the projectdoc Toolbox.


Section
titleRefresh

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.


Section
titleRebuild

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.


Section
titleUpgrade

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 

projectdoc-in-document-link-macro
anchorUpgrade Task
in this document.



projectdoc-section
titleSpecial Cases

Special cases that are rarely used. If an incident happend, the usual process to run would be refresh or a rebuild. The processes revalidate and repair may be useful if other maintenance processes take advantage of the invalid flag or the version number.

MaintenanceDescription
Revalidate

Recalculates document properties for all invalid projectdoc documents.

This is rarely necessary in the context of maintenance 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 in the context of maintenance 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.


Section
titleRevalidate

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

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.


Section
titleRepair

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.



Section
titleFuture Use Cases

The following use cases are not yet available. The are reserved for special use case the projectdoc Toolbox may support in the future.

MaintenanceDescription
Update

Traverses the persistence structure to add new information. This is typically used to add new artificial properties, but leaves existing properties untouched.

This process is currently not available and defaults to Refresh.

Repopulate

Used if the source for document information is provided externally.

This process is currently not available and reserved as a term for future versions of the projectdoc Toolbox.



...

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

...

About

This site is maintained by smartics.

Imprint / Impressum

Data Privacy / Datenschutz 

End User License Agreement (EULA)


To get in touch please send us an e-mail!

smartics email

Keep up-to-date!

Read our

smartics Blog

Follow us on

Twitter YouTube Prezi

Find us on

Bitbucket GitHub Atlassian Marketplace

Powered by




© 2001-2023 smartics - Kronseder & Reiner GmbH