When a spreadsheet is converted into a wrap, a database table is created to store the wrap instances. If you later modify the source spreadsheet – the wrap definition – the database may also need to be updated. This help page documents what you can and cannot do to a wrap after it has gone live.
ExcelWraps allows you to make changes very easily. Simply make the required changes to the source Excel file and “rewrap” – convert the spreadsheet again. As all wrap instance data is stored in the database using the Excel cell name, you need to proceed with caution to ensure that all old instances can be loaded by any newer version of the wrap.
As a rule of thumb, you can always add new fields, widgets, wrap functions or signatures to a wrap. If the new content doesn’t have a default value, it will just be empty or zero for existing instances. Removing content is far more complicated and something you really should avoid. Old wraps may have been signed and then it’s not really proper to change their content in any way, not even to remove data you later consider redundant.
To understand ExcelWraps, you need to be fluent in our terminology:
You can delete anything in a wrap that is not saved in the database. This includes all content on hidden worksheets. You can remove any widget that is not used for input, like Hide Rows/Sheets and Responsive Blocks. Feel free to delete any static text like headings, captions or help text. All static images can be removed.
To delete a field, widget, wrap function or signature that has been stored at least once in the live production database is not a trivial task. One reason for this is that one or more instances may already have been signed and then it’s not really proper to change their content in any way, not even to remove data you later consider redundant for the signature. Instead of deleting fields that you will no longer use, you can often just hide them. Otherwise, our client services team may be able to help you if you feel a wrap needs cleaning up.
From Wrap Instance view in the site dashboard, you may select the action Recalculate all Marked Instances to bring all existing instances up to date with the latest version of the wrap.
A lock is placed on the wrap whilst Recalculate Instances is running and this will prevent any users from using the wrap. After Recalculate Instances has finished successfully, the Wrap is unlocked and available for use again. For this reason, Recalculate Instances is best run out of normal hours to prevent disruption.
The following principles guide the recalculate instances (recalc) process:
The table below shows the common recalculation procedures when updating a wrap definition.
|Import Option||Mark for Recalculation Action||Action|
|Recalc all Instances||None (thus all marked for recalculation)||Not required||Recalculate all marked instances|
|Recalc Live Instances||Unmark for Recalc||Select all with ‘Live’ filter active, then ‘Mark selected instances for Recalculation’||Recalculate all marked instances|
|Recalc Selected Instances||Unmark for Recalc||‘Mark selected instances for Recalculation’||Recalculate all marked instances|
The table below shows the behaviour of a live and frozen wrap when loaded and when subject to Recalculate Instances (recalc).
|Use latest wrap definition||Y||Y||Y||Y|
|Save updated values to Database||Y||N||Y||Y|
The latest version of the wrap definition is used in both cases and old versions of the wrap definition are not retained.
The load and recalc behaviour of live wrap instances is the same and we can be relatively more relaxed about changes to live data. For frozen wrap instances, however, the ‘load’ and ‘recalc’ behaviour is very different with respect to wraplinks and the values stored in the database.
Users need to understand that recalculating instances is more powerful (and therefore more dangerous) than simply loading a wrap. Use ‘Recalculate Instances’ on frozen instances with caution and be fully aware of the impact any changes will make.
Wrap load behaviour is aimed at making as few changes as possible to the wrap instance, making a best attempt to preserve signature integrity. Calculated values will change on the screen in line with the new wrap definition but these changes are not committed to the data values stored in the database.
Wrap recalculation allows you to make changes to values stored in the database and is aimed at bringing old data in line with new calculation methods.
What happens to signatures collected on a previous version of the wrap? How do we overcome the dilemma that a wrap instance was signed with an old version of the wrap definition and not the latest one?
There are two ways to handle this:
1) Change the Wrap Name to Maintain Signature Integrity: Some people who place great emphasis on signature integrity would always select this approach to avoid complications from Recalculating instances ever arising altogether. Simply change the source Excel file name, make your changes and create a new wrap with the new name to take over from the previous version. MyWraps reports allow wrap appending, so that data from many versions of the wrap can be seen in the same table/chart.
2) Keep Wrap Name but Compromise Signature Integrity: Some people place a great emphasis on reusing existing data and updating as the wrap calculation evolves. This is particularly true when wraps are first being developed and it allows you to get started immediately with a ‘quick and dirty’ approach and evolve over time to a slick and elegant approach. To achieve this keep the same source Excel file name, make the changes in Excel and install the new version of the wrap over the old. Administrators use the Recalculate Instances button to bring all existing instances up to date with the new Wrap definition. The wrap name has not changed and all the instances made with the previous version can be read by the new version and you continue to use MyWraps reports to view the results of all instances. However, signatures made on instances of a previous version of the wrap may have been signed with possibly different calculated values or the appearance of the wrap may have changed. We would recommend keeping a change log so that the implications of the change over time can be assessed.
This presents us with a signature integrity issue. Any signatures older than the current wrap installation date will be prefixed by an ‘ character to signify the signature integrity issue. If the signature enabling cell logic also has changed, the instance may show up as signed even though the signature is not enabled (which presents an interesting conundrum).
Generally, we recommend this approach, but ask users to be mindful of the consequences of the signature integrity issue. It is a good idea to maintain a version history of the wrap to fully understand any signature integrity issues. A version history control can be created by another wrap in which the relevant roles sign to accept the change introduced, thereby maintaining signature integrity.
The above is an example of a valid signature.
The above signature was made before the latest version of the wrap was installed.
Here, a signature was made before the latest version of the wrap was installed and the new logic for the enabling cell would prevent the instance from being signed.
You can use simple logic for the signature enabling cell that ensures that both old instances and new instances always satisfy the appropriate cell enabling logic. The easiest way to do this is to use a Holder widget containing the creation date for the Wrap instance. In the enabling cell, you can then use an =if() statement to use different enabling logic based on the creation date for the Wrap instance.
Imagine if your labour rate changes after a particular date. In a wrap, you may update the calculation method using an Excel IF() formula. In these circumstances, you would install the wrap selecting the Unmark for Recalculate instances check box. From the wrap instances listing, select only those wrap instances which will be affected by the change and recalculate only them (as these are the only wraps that will change). If these controls were not in place and there were many thousands of wrap instances, recalculating all the instances would be very time consuming – and in fact unnecessary. This approach should only be undertaken with care.
Any input cell (including any with data validation drop-down selections) can become a dropdown menu or WrapLinkList in a new version of a Wrap. Data collected with the former input cell definition will be displayed in the dropdown or WrapLinkList with the Wrap definition, even if it is not included in the current list of options.
Example: A train operating company has three depots called A, B, and C. After some time, depot B is closed permanently, and the B choice is therefore removed from the dropdown for the “carriage belongs to” property. If you open the Wrap instances for carriages registered on the B depot, they will still have this field set to B – and can still be saved with that setting. However, if a new selection is made, B is no longer one of the choices in the list.
If the data held in an old wrap instance is not available in the current Wrap definition, it will be highlighted with a red border around the dropdown.