What is the archive module?

The archive module is an optional extra to the Please Review license. The archive workgroup setting only actually archives if this is also enabled on the license. It means that certain data from review is output to a zip file in a location accessible by the Please Review server. 

Archiving in the review workflow

Without the archive module, the review workflow, solely on the Please Review side of things, on a standard review, basically looks like this:

1. Review is created in Please Review

2. Review is closed and completed.

3. Documents with comments/changes and/or reports are downloaded and/or checked in to a document management system.

4. Review is deleted. If the recycle bin is enabled it will go there

5. Review is purged (completely deleted) after the recycle bin time limit has passed or immediately if the recycle bin is not enabled.

With the archive module it looks like this:

1. Review is created in Please Review

2. Review is closed and completed.

3. Documents with comments/changes and/or reports are downloaded and/or checked in to a document management system.

4. Review is deleted. If the recycle bin is enabled it will go there

5. Review is set for purging BUT it will first attempt to archive, after the recylce bin time limit has passed or immediately if the recycle bin is not enabled.

6. Only once it has archive successfully will it then purge (completely delete) 

Important exceptions

Note that any review that has had allow archiving set to DENY in the review settings will be excluded from this. If you delete such a review it will NOT be archived and the data will be purged when it comes to that point of the process.

Any review that is based on the OpenSpaces review type will be purged without archiving as archiving is unsupported for this review type. There is no setting that can be overridden for these to enable this. The reason for this is that is considered for this review type that such data retention will be done on the SharePoint side.

Configuring archiving

There are 2 options for doing this:

1. The simplest and most frequently used way of doing this is to edit the config line in the Runtime\Config\Config.xml file that looks like this, by default:

 <add key="Tara.Review.Archive" value="{workgroupid}/{date:yyyyMM}/{ReviewId}/{ReviewTitle}.zip" />

The comment in the file above this line explain the values here but this is also covered in the Advanced Features Guide on the Admin help page.

2. The archive Runtime\Config\ArchiveConfig.xml file can be configured. By default this is called ArchiveConfig.xml.template so you would copy it to a file without the '.template' extension if you were to use this.

This allows reviews to be the folder the archive files are output to, be more dynamic based on search criteria. For this to be reliable, the criteria involved need to something that would not overlap with other criteria as otherwise you might find the archive is output in one folder and not the other, when the other was possibly more important for it to sit in.  E.g, Lets say you reviews that have "ProductA" in their name, and some that have "ProductB" in their name and the ArchiveConfig is configured to search out each one to place these into separate archive sets. If you then have a review that features BOTH "ProductA" and "ProductB" in it's name, it's only going to in one of these archive sets. Therefore, you should only use this method if you are confident, you can configure it accordingly. The majority of archive module users just use the first option here.

More details on configuring this are covered in the Advanced Features Guide on the Admin help page.

Enabling Archive

To enable the Please Review license MUST have the license module included. If you are not sure if you have archiving included, please check with your account manager or Support. If you have recently acquired a license with archiving to replace one without licensing, it is important to restart both the web application (TaraWeb) and the background service (TaraService) to ensure these components know this change is in place.

The workgroup setting may show that archiving is already permitted but for this to work correctly, you not only have to have configured this but also have it o your license. Even if this shows PERMIT, if you do not have this enabled on your license, it will not work.

When enabling archiving, it is STRONGLY advised to delete and purge a dummy review first to be sure that this does go to an archive. This is especially good for testing the configuration is as desired too.

Also note that as it is a Root workgroup setting that has the option to allow an override by default, you might want to change the allow override option to NO, unless you want the possibility of sub workgroups on the system not having their reviews archived.

Important Note: Changing this setting after reviews have been created does NOT change the existing settings reviews may have. If users have already set a review to DENY, the review type has this set to DENY or the review type is based on the OpenSpaces review type, that doesn't support archiving, then those reviews will be purged without being archived.

What is included in the archive files?

The archive will contain the original document and the reconciliation report, along with some extra configuration data about the review. An example zip file layout looks like this:

Note that if there are too many documents for a single reconciliation report to generate successfully, there may be multiple reconcillation reports, one for each document instead. All the same data will be there but it might just be split out separately.

To explain why this splitting might happen, Please Review normally combines all reconciliation reports for all the documents on a review into one reconcillation report. It uses the styles of each original document to format the text it shows in the report. For example, if there is a review with 10 Word documents, each with 500 styles in them, it would need to copy each set of 500 styles into the Word document it generates for the reconcillation report. It does not matter if not all of the styles are used in the text involved or even in the original document. It also does not matter if the styles are identical between the documents as there is no distinguishing done at this point. The total of all these styles would make 5,000 and Word has a max limit of 4,079. As a document generated with 5,000 would be not supported by Word, this is an example of a situation where Please Review would not combine the reconcillation reports into one report, and output them separately instead.

Looking back at all the data exported, whilst technically the data is all there for the review, including the configuration, this cannot be used for putting the data back into a Please Review review as there exists no application or script to do this. So therefore it is important to consider this a one way process.

As for the information in the metainfo.xml file, this is included for information only. If users wished to code/script something to do a further task with this data, then that would be up to them, as this would be outside of the standard scope of the Please Review product and it's support. 

A sample file is attached here where the id was used as the filename: 108.zip

Benefits of archiving

Normal use of archiving would be to have it archiving your reviews as you go along. This helps keep the system tidier. It also helps to avoid using Please Review as a mass storage system too. 

Each document on a review consumes space on the server. We not only store the original files but also files for rendering in the browser and files we need for the processing of the document downloads and recon reports. Word documents can consume around 10x the size of the original word file in terms of background data on the server, sometimes even more than that. When you archive this data, you free up space on the server.

All this can help aid the performance of Please Review too for things like searching through the old reviews as there will be less to search through. It can also help speed up and cut down the overheads on the server backups that those responsible for the server would possibly be making.

Mass archiving

Whilst archiving as you go along is one way of using archiving, some customers consider archiving after data has built up, and their Please Review instance has a large amount of reviews that they want to archive off the system. Features in Please Review that make mass archiving possible are the highlighted workgroup settings shown that I will now explain:

With Auto-complete days set to a value other than -1, Please Review will regularly check to see if reviews are overdue, without any activity, and if they have been overdue and inactive for however many days set, they will be auto-completed.

Note that this does not apply to ALL review types. For example. reviews requiring decisions as to whether the content is carried over from one to the next, such as multi-phase reviews, will not auto complete, unless they are the last review in the phase. Those will have to be completed or deleted manually.

With Auto-delete enabled and the Auto-delete days set to a value other than -1, Please Review will delete completed reviews after the number of days set here.

Finally, there is the Recycle purge days (Review) setting, that determines how long reviews will remain in the recycle bin before being deleted. If this is set to 0 the recycle bin does not exist and when you delete a review it is deleted.

All these settings working together, along with the archive having been configured and enabled will cause the Please Review system to work thought the reviews completing, deleting, and archiving (at the time of purging), the reviews.

IMPORTANT: I would reiterate the point about testing the archive process works by deleting and purging a dummy review here first is VITAL. If it is not working and you configure all those settings to start eventually purging your review data, it will be purging them and not archiving them so the data will be lost. You use these settings at your own risk.

API methods

If they customer has paid for API access, they may be able to use that method download data or delete it too, but that is outside the scope of standard Support to advise on and they would need to pay for the API SDK pack and to go from there.

How long does it take?

If you are just archiving reviews as you go along, they are done at the time of full deletion (purging if you have the recycle bin enabled). This could take a minute or so. but it really depends on the amount of data involved with the review, how many documents on that review and how many comments and changes are in it.

If you are looking at mass archiving, again that depends on how much data there is to process. It also depends on how busy the system is as the archiving process will look to run when the system is not too busy. If documents are preparing, for example, this requires the background service to process these, so the archiving will look to avoid running whilst documents are preparing.

However, because it uses the background Please Review windows service (TaraService) to perform the tasks, the main Please Review web application (TaraWeb) can run just fine. This means that users should not notice the mass archiving running in the background.

I would allow a few weeks if working with a lot of data but note that the more data involved and the older the data, the higher the chance that you might encounter a review you need to manually workaround, as covered below. Extra time may need to be allocated for this.

Hosted Customers

For hosted customers, access to the files can be made available. Previously, when this has been done for mass archiving of files, our secure download facility has been used for this, containing all the individual zip files zipped into a bigger file or files accordingly to be downloaded there. If this was to be used in an ongoing basis, or other forms of access would need to be required, then these would need to be discussed with your account manager, who can work this out with our Implementation Team and Cloud Ops teams who would be responsible for setting this up.

Known limitations

In some rare cases, the reconciliation report might fail to generate. In the latest Please Review versions it will try these to archive each review 3 times, just in case someone restarted the server whilst it was midway throguh an archive, for example. If each time it fails, it will mark that review as failng to archive and move on to the next ones. When the archiving has completed, these reviews will be the ones that are left. Support can help with these and the review may have to be downloaded manually.  

That said, one option might be to upgrade to a newer version of Please Review as it is possible that we might have fixed whatever caused the reconciliation report generation to fail, since we are always improving the handling of the reports. Additionally, the archive process itself has also been improved since earlier versions too.

However, it should also be noted that Please Review versions only support archiving of files generated so many versions back. For example, v5.2 only supports the archiving of reviews that were created since around v4.5. This is in line with the reconcillation report generation too as there were major changes, certainly with how we handled Word documents. Therefore, if users are archiving a lot of reviews created in much older versions, we would recommend contacting Support to discuss the best way forward.