The WrapStack function allows advanced users to perform bulk operations on wrap instances. Users can insert new instances, update existing instances, or add fields to a wrap. This can save considerable time when many new instances need to be created regularly, e.g. for daily inspection, or when the same change needs to be done to many or all wrap instances.
When wrap instances are used to document work that is repeated regularly, users may have to enter the same data over and over again. WrapStack offers a simple structure for automation of such monotonous processes, where users can easily prefill or prepopulate the database with all the necessary checklists.
WrapStack can also be used to assign a new value to one or more fields in existing wrap instances, or add one or more new fields to all wrap instances.
You can manually create a static list of the Unique Keys that are to be inserted or updated in bulk. If the operation affects several instances, it may be easier to create a MyWraps report that contains all the Unique Keys that you want to participate in the bulk operation. Driven by the Unique Keys in the MyWraps report, WrapStack automatically inserts new or updates existing instances in the target wrap with the field contents you have provided.
All WrapStack operations are serialized through a job queue that ensures that the database is never overloaded by background operations. To further reduce the load on the system, we recommend that you retain the default option to not recalculate instances while they are being added or updated. In most cases, it is better to save this for later.
Example: At the beginning of a day, it is known what trains will arrive at a depot for inspection. A WrapStack job is used to create a new instance of a daily inspection checklist for each carriage in each train that arrives at the depot. The correct checklist is used for each type of carriage in the train.
When WrapStack enqueues a job, you can log the event in the Audit Trail.
To use WrapStack, you build a “control” wrap that contains one or more WrapStack functions. The control wrap initiates the background jobs that perform the requested bulk operations.
When you convert this spreadsheet to a wrap, each WrapStack function appears as a Create Instances button. The user presses this button to initiate the bulk operation.
Each WrapStack function in the control wrap has an instance data table that describes the bulk operations it will perform. In the screenshot above, the instance data table is marked with yellow. The contents of the instance data table are described in detail below.
An error in your instance data table may result in an attempt to create an instance of the Target that already exists. If you have selected Create instances as the Action for the WrapStack function, this will terminate the operation.
Example: a daily inspection wrap contains the inspection date as part of the Unique Key. When using WrapStack, you can insert today’s date automatically. All the new instances will now have a unique key, since today’s date wouldn’t have been used for any previous daily inspection.
An error in your instance data table may result in an attempt to update an instance of the Target that doesn’t exist. If you have selected Update instances as the Action for the WrapStack function, this will terminate the operation.
Example: a daily inspection wrap contains the inspection date as part of the Unique Key. When using WrapStack with a Source MyWraps report that doesn’t contain a date, you must insert the appropriate date using the instance data table. You can then update all the existing instances that have the Unique Keys provided by the Source MyWraps report and the date specified in the instance data table.
The WrapStack function also has an Action to both Update existing instances and create new instances. If a Unique Key already exists, the instance will be updated, if not it will be inserted as a new instance. This ensures that all Unique Keys provided by the Source MyWraps report and the instance data table exist for the Target wrap.
However, it also increases the risk of errors, and you may want to consider running this as two separate jobs, one Create and one Update job, to have the Unique Keys properly validated as non-existing (for the Create job)) and existing (for the Update job).
The TargetWrap column is the left-most column in the instance data table, and contains the name of the wrap that is subject to the bulk operation defined by the row.
If this column is empty for a row in the instance data table, the row is ignored. This makes it possible for you to design an “intelligent” data table that manipulates a variable number of instances, e.g. for trains that appear in different fixed combinations of carriages.
To create such an intelligent table entry, you can use function calls similar to this:
The column heading for this column must be TargetWrap.
The SourceMyWraps column is the right-most column in the instance data table. It allows you to finely designate what instances you want to manipulate for each row in the instance data table, by using a MyWraps report to provide their Unique Keys.
The Source MyWraps report is created just like any other report in MyWraps. You will spend most of the time tweaking the filters in the report to ensure that it generates exactly the Unique Keys that you want to create in the Target. Remember that you can use filters also on columns that are not included in the report.
When the report fulfills your requirements, you copy the second half of the MyWraps link (everything after /MyWraps/, in blue below) from the browser’s Address field to the SourceMyWraps column.
The SourceMyWraps report is only used to provide the Unique Keys for each wrap instance that is affected by the bulk operation. Any data you want to insert into the affected wrap instances must be provided as static content, see below.
The column heading for this column must be SourceMyWraps.
There are several types of static content for the new wrap instances that you may want to provide in the instance data table:
A column in the instance data table that provides static content for a field in the wrap must use the field name as the column header. If you want to assign a value to a field called inspection_date in the wrap, the heading for this column in the instance data table must be inspection_date. All field names must be in lower case.
It is possible to manipulate two or more wrap instances in the Target wrap for each instance in the Source MyWraps report. This usually happens when the Target wrap has additional Unique Keys that are provided in the instance data table. In the example below, the Target has a Projectcode key. For each instance in the Source Mywraps report, WrapStack will generate or update one instance of Target with Projectcode A, one with Projectcode B and one with Projectcode set to C. All other components of the Unique Key for the new instances of the Target are provided by the Source MyWraps report.
You can provide static content for the following reserved field names:
The WrapStack function can affect many wrap instances, which can create heavy extra load on the database infrastructure. WrapStack places the entire bulk operation as a wrap job on the Wrapsite’s server queue. All the database operations for one WrapStack function are run as one wrap job.
After a user press Create instances and a wrap job has been queued in order to perform the required database operations, the user gets a wrap job ID in return. The Wrap job id appears in the confirmation message
and in the Wrap at the position of the WrapStack function. You should instruct users to save this job ID for future reference.
You can follow the serialized processes by monitoring the Wrap Jobs queue on the wrapsite. Learn more on the Wrap administration help page.
If you want the control wrap to offer a link to the Wrap Jobs Queue, you can use the following formula in the source spreadsheet:
=HYPERLINK("/MoreVision.ExcelWraps/WrapJobsAdmin" ,"Wrap Jobs Queue")
In the example above, the bulk action defaults to “create new instances”. New instances will be created for the WrapStackTarget wrap. One instance will be created for each Unique Key in the Source MyWraps report. If the Unique Key already exists, the job will be terminated.
The following cell formula is inserted in the cell.
=WrapStack(instance_data_table, recalculate_instances, action)
Each WrapStack function is associated with an instance data table in a designated cell range. The format of this table is described under Definitions above.
If you don’t specify a valid cell range, the conversion will fail.
If you want to execute all the formulas, WrapLinks, etc for each instance already during the bulk operation, set the recalculate_instances option to True. This will make the bulk operation considerably slower than if you allow this to happen the next time each wrap instance is opened.
The default is False.
Select the bulk operation to be performed using an integer 1-2:
The default is 1.
When WrapStack processing is complete, the WrapStack function returns the job id.