For organisations that require multiple users to be working on the same report, being able to track changes on your documents is an essential feature.
How does it work?
Each time the user saves a change on a report in Report Writer, a revision history is created and the main document is updated. A revision history is a snapshot of the entire document content at a point in time with relevant metadata such as the author, created date, and created time.
Three statuses are configured by default:
Comments can be added to the document at any time, for any status other than “published”. Comments are displayed as a list in the right blade.
Calculating conflicts or saving the document
When a user attempts to save, the ID of the revision history they started at and their current revision is checked for conflicts between the current revision and the revision history. If changes exist, a list of conflicts will be calculated by comparing the current revision and the revision history immediately proceeding it chronologically. If there are no conflicts, the document will save successfully.
Conflicts are displayed as a list of fields which have changed values which conflict with the values the user has in their current version of the document, with time and author data. In the case of the first revision history or the current user being the author of the previous saved version, there are no conflicts.
Fields have a history of all changes that have been made, this is the differences between all history revisions (or a subset) as a list of field values with some metadata such as author and time.
When a document is “in review” the content is locked but comments can be left. The document can be moved back into any other status and changes can then be made again.
Push-pull vs pull-push and resolving conflicts
A usability decision was made to allow a user to save their changes to a report “out-of-band”. This has considerations regarding conflicts.
If a user goes offline, when they come back online there may have been saves by other users where the values of some fields are in conflict. This presents two options:
Should they be forced to pull other users changes and resolve conflicts before saving again?
Should they be able to save their changes (thus their version becomes the authoritative latest report) and be informed of any conflicts with any changes made by other users?
The first option also presents challenges with the possibility that there may be many saved changes from other users whilst the user was offline. It also means that the state of the document is definitive.
The decision was made to go to a pull-push model and display any conflicts on fields between the users current version and any revision history since the last time the status changed away from “in review”.
The user is forced to resolve conflicts before saving the document.