Note: This section has been replaced. Please continue to the updated and extended help page at https://help.excelwraps.com/support/online-help/introduction-to-wraps/

It is important that you understand the difference between a wrap and a wrap instance. They are analogous to an Excel template and an Excel workbook.

A wrap is used repeatedly and the information contained in the wrap is saved as a wrap instance. Each wrap instance is given a unique number (ID) or a unique key combination.

So what is the difference between an ID and a unique key combination? Imagine a shoe shop, each shoe in the shop will have a product ID, say the shoe you want is ID 1569. Since you do not know any product IDs you ask for a pair of size 9 Doctor Martin’s black boots. The unique key combination of Size (9), Brand (Dr Martin’s), Colour (Black) and Style (Boot) tells the shopkeeper exactly what you want. The unique key combination resolves to the Product ID but it is much easier to remember. When you view all wrap instances from the site you will see both the ID and the unique keys combination arranged in rows.

In this example a wrap called W-BOS-A-15-QCOI0001 is a form for recording some overhaul activities for a train unit. The work must be completed every 500,000 miles. It uses the unique keys of 'unit' and 'mileage' and 12 individual wrap instances have already been created. Each instance takes a row in the table where you can see both the ID and the unique key combination (e.g. wrap instance ID 40061 has the unique key combination of unit=395008 and mileage=1,000,000).

Note:

• An AutoNumber is used as a unique key when a wrap will be used an indefinite number of times.
• Values are located in the database using the unique key combination (or ID) and the spreadsheet cell name. 
• MyWraps database searches on specific unique keys are faster than searches on non unique key cell searches. A first pass filter uses the unique key combination followed by a second pass filtering the non-unique key cell values.

Notes for Administrators only:

1) Creating Wrap Instances In Excel:

XLW's WRAPINSTANCE() function can insert up to 26 pairs of cell name and cell value separated by commas. Cell names that are unique keys are specified and the combination of unique keys will identify a particular wrap instance (a new unique key combination will create a new instance or an existing unique key combination will update cell values in an existing wrap instance). It is also possible to poke in wrap instance creation date, Wrap Instance creator, wrap instance AdminFreeze Boolean, wrap instance Freeze Boolean and wrap instance awaiting signature Boolean.This method is a direct modification of values in the database and care must be taken that the calculation method in the wrap definition is consistent. 

Administrators can import new Wrap Instance XML files created using XLW new WRAPINSTANCE() fuction. A new new ‘Import Instances’ button on the Dashboard wrap instance listing will load in the file. It can both create new and update existing wrap instances.

'Import Instances' is much faster method than our ‘Recalculate Instances’ method, which requires each instance to be recalculated by a browser and is more appropriate for large data sets (wraps with many Wrap Instances).

'Import Instances' is much faster method than our  ‘Initialise Instances’ method for pre-population, which requires each instance to be recalculated by a browser and is more appropriate for large data sets (wraps with many Wrap Instances).

2) Creating Wrap Instances with WrapStack in WrapCreator

Note: This section has been replaced by an updated and extended help page for WrapCreator at https://help.excelwraps.com/support/online-help/help-the-wrapstack-widget/

WrapStack is a construct built in wraps to automatically create wrap instances. WrapStack is a range of cells including a 'TargetWrap', a cell value collection spanning as many columns as required and a 'Source' which is generally a MyWraps report URL instruction.

Imagine that a number of tasks wraps already exist for an old construction project. These can be listed in a MyWraps report defined by "/MyWraps/Task?Options.columns=Project,TaskID,Task,Who" which looks like the table below.

If we won a new construction project then we could use the Shed 1 project as the 'source' of new target Task wrap for the "Shed 2" project. The cell value collection includes TaskID with a value * (a sequential integer assigned by the server) and a cell called 'Project' contains the value "Shed 2". The WrapStack for this would look like this:

Executing the wraps stack would created three new instances (TaskID=4, 5, and 6) In a cell called Project in the Task target wrap we will insert the value 'Shed 2'. Now if we use the same MyWraps report ("/MyWraps/Task?Options.columns=Project,TaskID,Task,Who") we would show the 3 new tasks we have created:

In our example above the WrapStack only contains one active row but it can contain many rows (e.g. let's create project Shed 2 and Shed 3 at the same time).

In our example the source and target used the same Task wrap although this does not have to be the case. For example a wrap called JobDefinition with a unique key JobID can be listed in a MyWraps source to target examinations for a particular train unit creating many instances (each of the form Exam?JobID=5&Unit=395001). Generally source and target wraps use the some of the same unique keys.

WrapStack has a calculation option which if TRUE performs calculations in a backend queue after this is completed all cell values are updated. Alternatively the calculation option can be set to FALSE and wrapstack simply inserts the cell values collection into the instance without recalculation (this is obviously a faster process and useful when a recalculation is not necessary). Wrapstack also has a control option to identify if the wrapstack is being used to create new instances, to update new instances or both. Wrapstack is very powerful and can create many instances. It has an undo feature in case instances are created in error.