Wrap administration

The ExcelWraps pages on the Wrapsite define each Wrap and the Wrapgroups. This is where you download the Wrapsite properties for WrapCreator and design wraps that you then upload on the same page. Two job queues show you the status of tasks that run in the background.

Screenshot of the ExcelWraps group in the ExcelWraps administrative dashboard

  • Wrap Definitions – When you click on ExcelWraps in the sidebar of the Administration dashboard, you get to the Wrap Definitions page where all your Wraps live. Every time you make changes to a Wrap with WrapCreator you must upload the new definition here to make it active. You can edit all the data instances of a Wrap and change or remove incorrect instances.
  • Wrap Groups – In the permissions model, Wraps belong to Wrapgroups that specify the rights that the various user roles have. You define the Wrapgroup names here and assign Wraps to them.
  • Wrapsite properties – To design and edit Wraps, you use a special add-in for Excel called WrapCreator. You need to regularly download a summary file with the Wrapsite properties to WrapCreator, so that it has the information it needs about the currently defined Users, Workgroups, Wraps and Wrapgroups on the Wrapsite.
  • Server Recalculation Queue – Sometimes, the Wrapsite needs to recalculate some or all live instances of a Wrap. This can be a time-consuming and resource-intensive operation, and so it is serialized to avoid overloading the server. Instances pending recalculation are visible on the Server Recalculation Queue.
  • Server Queue – Most work on the wrapsite is performed immediately, to provide rapid response times to Wrap users. A few types of work need to be run only one at a time, to ensure that the server isn’t overloaded. As an example, administrators can use WrapStack to prepare a lot of Wrap instances for an incoming train. Such serialized units of work are called Wrap jobs. The Server Queue is a job queue for the wrap jobs that are awaiting execution.
  • The Wrap-related Wrapsite settings are described at the end of this document and control things such as instance locking and what Roles to use for the Wrap.

The Audit Trail

Many system events related to Wraps can be logged in the Audit Trail, e.g. when Wraps are created, updated, or deleted.

The Audit Trail can also register every time Wrap instances are created, viewed, updated, deleted, signed, or unsigned.

Wrap Definitions

The Wrap Definitions page is the home for all the Wraps in your Wrapsite. Use the Wrap Definitions page to import new or updated Wraps. You can set various properties of each Wrap and manipulate its instances.

Page header

Screenshot of the Wrap Definitions on the ExcelWraps tab of the Administration dashboard

The Apply button performs the action selected in the Actions menu for the selected Wraps. For this Action menu, you can only select Delete. The Wraps that you have selected and all their instances are queued for deletion after which you are taken to the server queue where you can follow the job that was created. If you delete a Wrap, you must upload the definition again if you want to regain access to it. If you delete a Wrap’s all instances, we may be able to restore most of them from the backups we make of each Wrap, but you risk losing all additions or edits made since the most recent backup. Deleting Wraps and instances is a very rare operation that you would normally do only during development and testing.

The search box is used to find Wraps by name – just enter a part of the name and press Enter. The Filter setting allows you to show all Wrap definitions or only the ones that are locked (disabled). The Sort by setting allows you to order the Wraps by Name, Last Updated time or Wrap Groups. Press the Filter button to apply the filter and sorting settings and refresh the list of Wraps.

Import Wrap definitions

You design and edit Wraps with an add-in for Excel called WrapCreator. When the source spreadsheet is converted to a Wrap, you get a ZIP file that needs to be imported at the server. Click on the Import button to add new and update existing Wraps.

Screenshot of the Import Wrap Definition window

Click Browse… and navigate to the folder where the ZIP file from WrapCreator is located. Select the ZIP file and click OK.

During testing, you may want to Delete any existing instances.

When you update a Wrap, its instances are automatically recalculated to ensure that all the values in all the instances are calculated using the most recent formulas and static values in the Wrap. If you have only made layout changes, or if you plan to recalculate the affected instances manually, you may skip this step by ticking Unmark instances for recalculation.

When you import a new version of a Wrap and it no longer contains all the fields that were in the previous version, you get a warning message. This is because existing Wrap instances still have content for this field in the database but when you open them there is no place to show the missing field on the screen. When you save the instance in the new format, the old contents for the omitted field will be lost. By ticking Ignore warning for missing cells, the file will be imported without any checking for this.

List header

The down arrow selects all Wrap definitions.

The Name column contains the name of the Wrap.

The Groups column contains the names of the Wrapgroups that the Wrap belongs to.

The Action column allows you to download the source for the Wrap in xlsx format, edit the Wrap properties described below, or to Lock the Wrap to prevent Users from using it.

The Last Modified column contains a timestamp for the most recent update to the Wrap definition.

List entries

If you click on the name of a Wrap, you get to a list of its instances. If you click on an instance, it opens for editing.

Wrap Instances

If you click on the name of a Wrap, a list of its instances appears.

Screenshot of the list of instances for a Wrap

Page header

The Apply button performs the action selected in the Actions menu for the selected Wrap instances. The possible actions are:

  • Create New Instance – Opens an empty instance of the Wrap in your browser. If you save it, it is added as a new instance of the Wrap.
  • Export Wrap Definition – Wraps are defined in Excel, as spreadsheets, using the WrapCreator add-in for Excel. When you export a Wrap Definition, you download both the spreadsheet that was used to define the Wrap and the output from the conversion to a Wrap.
  • Export Wrap Definition with all instances – This will also include an XML file with all the data instances for the Wrap. You can use this to import large amounts of data into an analysis tool. For more information about exporting instance data, read the help page about MyWraps.
  • Export Definition and Selected Instances – This only exports the instances that you have selected in the list to an XML file.
  • Export Xlsx file – This only exports the source spreadsheet, without any instances or the output from the conversion to a Wrap.
  • Export Selected Instances – Exports the selected instances to an XML file, without the Wrap definition spreadsheet.
  • Mark Live Instances for Recalculation – If you have made changes to the Wrap definition, you may want to apply these changes also to existing instances that have not yet been signed off. This operation selects all the live instances (the ones that have not been frozen by a final signature) before you initiate their recalculation.
  • Mark Selected Instances for Recalculation – If you have manually selected one or more instances that you need to have recalculated using the most recent Wrap Definition, use this option to mark them before you initiate their recalculation.
  • Recalculate All Marked Instances – Places all the marked instances on the Server Recalculation Queue.
  • Initialise Instances – We previously used this function to pre-fill the Unique Keys for a group of new instances. This method of adding many new instances has been superseded by the WrapStack widget.
  • Delete Selected Instances – The instances that you have selected are queued for deletion after which you are taken to the server queue where you can follow the job that was created. If you delete a Wrap’s instances, we may be able to restore most of them from the daily backups we make of each Wrap, but you will lose all additions or edits made since the last backup. We can only restore all the instances in the backup, not just the ones you deleted by mistake. Deleting Wraps and instances is a very rare operation that you would normally do only during development and testing.

Press the Filter button to select only the instances that are in the Live or Frozen state, are awaiting your signature or have previously been signed by you.

  • Live – Show all wrap instances not yet frozen, i.e. work in progress. Wraps freeze when the last signature has been made to indicate the completion of a process.
  • Frozen – Show instances that are frozen by a final signature and cannot be modified further.
  • AwaitingSignature – Show wrap instances that are waiting for your signature.
  • SignedByMe – Show wrap instances that you have signed.
  • Any – Shows you all instances.

List header

The down arrow selects all the Wrap’s instances.

The columns in the list are the Unique Keys for the Wrap, which help you select the instances you are looking for.

You can type filter values into the text box at the top of each column to filter the list of instances. Read more about column filtering in the help page for MyWraps.

List entries

If you click on an instance, it opens for editing.

Edit Wrap Definition

Clicking on the Edit link for a Wrap Definition allows you to modify some of its properties.

Lock type

ExcelWraps is a multi-user system. There is always a risk that two or more users access the same Wrap instance simultaneously. For read-only access, this happens naturally and without conflicts, but if two users need to modify the Wrap instance and their requests overlap, a synchronization issue may occur.

Consider the following scenario:

  1. User Primo opens the wrap instance.
  2. User Secondo opens the wrap instance.
  3. Primo starts to edit the original version of the wrap instance.
  4. Secondo starts to edit the original version of the wrap instance.
  5. Primo submits an edited version of the original wrap instance.
  6. Secondo submits an edited version of the original wrap instance.

In step 6, the version saved by Secondo does not include the modifications made by Primo. The changes made by Primo will be overwritten and lost.

Optimistic locking

To prevent this, ExcelWraps uses a locking system that alerts Secondo that the wrap instance has been modified since he/she opened it. When this happens, Secondo has two options:

  1. Abandon the previous edit, re-open the latest version of the wrap instance, perform the same changes, and save.
  2. Contact Primo and resolve the situation.

This is referred to as optimistic locking and works well in most cases.

ExcelWraps is used to support workflow processes where it is unlikely that two users or workgroups would inspect the same carriage or repair the same fault. If you run into repeated conflicts like the one above, you may want to redesign the wrap, e.g. to use one wrap for the electrical checklist and one for the mechanical checklist, instead of having both checklists in the same wrap which may greatly increase the risk of conflicts.

Screenshot of the Lock type setting for a Wrap

Pessimistic locking

Optimistic locking is perfectly safe and there is no risk of overwriting a previous change to the wrap instance. However, if these conflicts happen very often, and the wrap cannot be redesigned to avoid them, ExcelWraps also offers an explicit locking model that we call pessimistic.

With pessimistic locking, users press a Request Edit Lock button to explicitly lock a wrap instance before they begin to edit it. When done, they use a Release Edit Lock button to allow other users to take the edit lock. Instead of having trouble when a rare conflict occurs, users now have extra steps to perform for every edit.

Unfortunately, users regularly forget to release the edit lock. Administrators can be called in to use a Seize Edit Lock button and then release the lock for others to take. Before doing this, they must verify that the lock isn’t held legitimately by a user that is performing a lengthy edit.

Pessimistic locking creates extra work for all involved. It is primarily useful when edits take a very long time because users need to perform many complicated manual operations while editing the wrap instance, e.g. when storing a large number of measured values. In this case, it may be more time-consuming to do all the measurements again in case of a locking conflict than to first acquire the lock explicitly. Again, consider redesigning the wrap to avoid simultaneous edits.

Default locking

The Wrapsite Settings contain an Edit Locking setting that sets the default lock type for an entire wrapsite.

Screenshot of the Settings link group on the ExcelWraps Administration dashboard  Screenshot of the Lock Type setting in the Wrapsite settings

Most users would have this set for Optimistic locking by default.

The None setting means that users will not be informed when data is lost due to locking conflicts. We recommend that you discuss your requirements with your client services team before you select this setting.

Wrapgroups

Each Wrap belongs to one or more Wrapgroups. These are part of the ExcelWraps permissions model and define what rights each user role has to the Wrap and its data.

You assign the Wrap to its Wrapgroups simply by ticking each group you want the wrap to be a member of.

Screenshot of the Wrapgroups list for a Wrap

The Wrapgroups are defined on the Groups tab, see below. Read more about Wrapgroups and permissions on the Wrapgroups and workgroups help page.

Print to PDF on Signature

Screenshot of the Print to PDF settings for a Wrap

You can have each Wrap instance printed as a PDF file when it is signed off. This makes it easy to confirm a completed process by e-mailing a “receipt”. Tick the Print to PDF on Signed/Unsigned checkbox to enable the feature. You can have the PDF file generated in landscape mode (longest side up) and zoomed to 0-100% of its normal size. The PDF file is stored with the instance.

The scheduling settings

This is where you enable a Wrap for automatic recalculation, including periodically creating new instances, e.g. when saving KPIs automatically.

Screenshot of the scheduling settings for a Wrap

Period

The KPIs in a WrapMap instance document the performance indicators for a given period. You select the length of the period that best fits your business needs.

  • Daily – KPIs are calculated separately for each day.
  • Weekly – KPIs are calculated for periods of seven days. If the Anchor Date falls on a Wednesday, every instance of the WrapMap will cover a seven-day period starting with a Wednesday and ending with the following Tuesday.
  • Every two weeks – KPIs are calculated for periods of fourteen days. If the Anchor Date falls on a Wednesday, each instance of the WrapMap will cover a period starting with a Wednesday and ending with the Tuesday almost two weeks later.
  • Every four weeks – KPIs are calculated for periods of twenty-eight days. If the Anchor Date falls on a Wednesday, each instance of the WrapMap will cover a period starting with a Wednesday and ending with the Tuesday almost four weeks later.
  • Monthly – KPIs are calculated across calendar months. If the Anchor Date is June 7, the first period that starts after the New Year covers January 7-February 6.
  • Quarterly – KPIs are calculated across calendar quarters. If the Anchor Date is June 7, the first period that starts after the New Year covers March 7-June 6.
  • Half Yearly – KPIs are calculated across half calendar years. If the Anchor Date is June 7, the first period that starts after the New Year covers June 7-December 6.
  • Yearly – The KPIs are calculated across calendar years. If the Anchor Date is June 7, the first period that starts after the New Year covers June 7-June 6.
  • Network Rail – This option offers support for the Network Rail Control Period used in Great Britain. Network Rail breaks a year into 13 periods all 28 days long apart from the first and the last which may be of a different length. The first period for the year always starts on April 1 and this will also be the starting date for the first saved KPI instance for the control period. The last instance for a year always provides KPI data for a period that ends on March 31. Since this schedule is slightly irregular, please set the Anchor Date to April 1.
  • Infinite – A single instance of the WrapMap is reused indefinitely. This is not practically useful for standard KPIs that are based on averages since the period becomes too long after a while. It is mainly useful for measurements that are only incremented, like usage time for appliances or accumulated distance for vehicles.

Anchor Date

We count the days of each period based on an Anchor Date, which can be any date in the past that would have been day 1 of the intended cycle.

The anchor date is only an abstract point of reference and does not imply that KPIs have been saved from that specific date. Performance data is not saved until you create the first instance of the WrapMap, the random “start” date if you will. The first instance contains the KPIs for the (possibly incomplete) first period, from the arbitrary start date to the end of the period as defined by the anchor date. Latter instances will cover full periods, starting and ending as defined by the period length, counting from the anchor date.

  • If you start collecting daily KPIs, you can set the anchor date to any past date.
  • If it’s Wednesday, July 15, and you start collecting KPIs for weekly periods running from Mondays to Sundays, you must set the anchor date to July 13 or any other past Monday.
  • If it’s Wednesday, July 15, and you start collecting KPIs for two-week or four-week periods running from Mondays to Sundays, you must set the anchor date to July 13 or any other past Monday that would have been day 1 of the intended cycle.
  • If it’s July 15 and you start collecting KPIs for full calendar months, quarters, half years, or years, you can set the anchor date to the first of any past month, quarter, half year or year, respectively.
  • There is no quarter Aug 31-Nov 31 and no half year May 31-Nov 31. You cannot start periods on day 29, 30, or 31 if the period is months, quarters, or half years, since these days don’t appear in all months.

Time

When triggered by the frequency setting, the ExcelWraps server automatically starts the recalculation of the current WrapMap instance at or slightly after the designated time, which is expressed relative to the UTC (Greenwich meridian) timezone.

Many businesses operate around the clock, like in transportation. In these cases, one often sees operating hours starting with the morning traffic, e.g. a business day can run from 04:30:00 to 04:29:59 the next calendar day and it is for this period the KPIs are collected. In this case, you probably don’t want the KPIs for the previous full day to be calculated until after 04:30, converted from your timezone to UTC.

Other businesses work across timezones. A company in Germany with most of its business on the US west coast may not want to recalculate “this week so far” KPIs until after 8:00 UTC the next day to occur after midnight in San Francisco.

Frequency

In most cases, you’ll want the current WrapMap instance to be recalculated daily, so that your analysts have up-to-date KPIs every day also for the current period. WrapMap recalculation is usually light work for the server. All the instances of the WrapMap that contain historical data were frozen at the end of their respective period, so recalculation only affects the single current WrapMap instance which in turn only aggregates data from the Wrap instances that provide performance indicators for the same specific timespan.

There is no technical reason to set this to any other value than 1 for daily recalculation. If your business needs dictate that some monthly KPIs are recalculated only every 7 days, you should set this value to 7.

You can only enter positive integers that are less than the period length. The frequency is reset when a new period starts. If the period is monthly and the frequency is 28 there will be only one interim recalculation, on day 28 of each period. If the period is monthly and you set the frequency to 32, interim recalculations will never occur and each WrapMap instance will only be recalculated at the beginning and end of its period.

The Wrap Groups

The Wrap Groups tab is where you define and manage your Wrapgroups. Each Wrap belongs to one or more Wrapgroups.

A Wrapgroup may be owned by a Workgroup, or be available for all Users. For each Wrapgroup you define the level of access per User Role.

Read more about Wrapgroups and permissions on the Wrapgroups and workgroups help page.

 

The Wrapsite properties

Designing Wraps in WrapCreator requires that the Excel add-in knows some basics about the Wrapsite, e.g. the Users, Roles, and Workgroups when adding widgets such as UserSelector. When you add a WrapLink, the add-in needs to know about your Wraps and Wrapgroups.

Screenshot of the Wrapsite Properties page of the Administration dashboard

When you press the Download button on the Wrapsite properties tab, a ZIP file is downloaded with all the details about the Wrapsite that WrapCreator needs to know. You load this file into WrapCreator on the Account tab of the task pane.

For WrapCreator to keep up with changes to the Wrapsite, you may need to update the Wrapsite properties in the add-in now and then. WrapCreator will function correctly without the most recent Wrapsite properties, but will be unable to create WrapLinks to Wraps it doesn’t know about or use Roles that were not included in the most recent set of Wrapsite properties.

Learn more on the help page for the Account tab on the WrapCreator task pane.

The Server Recalculation Queue

When a Wrap definition is changed, existing live Wraps may require recalculation to be brought up-to-date on the most recent formulas and defaults as defined in the Wrap. A recalculation operation can involve a lot of Wrap instances. If too many instances are recalculated at the same time, it may overload the server. This is why there is a Server Recalculation Queue on which all instances with a pending recalculation are placed, waiting for their turn to be recalculated.

You can follow the serialized processes by monitoring the Server Recalculation Queue on the Wrapsite. A new instance will enter the queue as Recalculation pending, get selected for recalculation when it is at the top of the queue, and then ticked off as Recalculated. If an error occurs, the instance is instead flagged as Recalculation failed.

To monitor the server recalculation queue, click on the ExcelWraps link in the left-hand sidebar of your Wrapsite Administration dashboard, then select the Server Recalculation Queue tab.

Screenshot of the Server Recalculation Queue for a Wrapsite

Page header

To manage wrap jobs on the queue, you tick one or more of their checkboxes in the list and then press Apply to perform one of the following Actions:

  • Retry – Try to recalculate an instance again.
  • Mark as recalculated – Removes the instance from the list of instances marked for recalculation.

Use the Filter dropdown and the Filter button to select what type of instances you want to work with on the dashboard.

  • Initialisation Failed – Initialisation was a predecessor to the WrapStack widget.
  • Initialisation Pending – The Initilisation functions are rarely used anymore.
  • Recalculation Failed – An error occurred during recalculation.
  • Recalculation Pending – The instance has been marked for recalculation.

The Server Queue

Most work on the wrapsite is performed immediately, to provide rapid response times to Wrap users. A few types of work need to be run only one at a time, to ensure that the server isn’t overloaded. Such serialized units of work are called Wrap jobs. The ExcelWraps job queue contains the Wrap jobs that are waiting to be run.

You can follow the serialized processes by monitoring the Server Queue on the Wrapsite. A new job will enter the queue as Pending, get selected and run when it is at the top of the queue, and then ticked off as Complete. If an error occurs, the job is instead flagged as Failed.

To monitor the job queue, click on the ExcelWraps link in the left-hand sidebar of your wrapsite dashboard, then select the Server Queue tab.

Screenshot of a job queue in ExcelWraps

Page header

To manage wrap jobs on the queue, you tick one or more of their checkboxes in the list and then press Apply to perform one of the following Actions:

  • Retry – Try to run a pending job again.
  • Remove – Remove a job from the queue to prevent it from being executed.
  • Undo – Rollback all the changes for an incorrectly designed job, i.e. remove the wrap instances that were created and restore the field contents that were updated in existing instances.

Use the Filter dropdown and the Filter button to select what type of jobs you want to work with on the dashboard.

  • Pending – The job is awaiting execution.
  • Failed – The job failed during execution.
  • Complete – The job was run without errors.
  • Removed – The job was removed from the queue before execution.
  • Undo Pending – The job has been marked for undo, i.e. reverting all changes it made to the database.
  • Undo Failed – The undo operation failed.
  • Undone – All the database changes for the job have been successfully undone.

Settings related to Wrap administration

There is a group of settings on the Administration dashboard > Settings > ExcelWraps that control Wrap administration.

  • Edit locking – Two Users cannot edit the same instance at the same time. The default locking method is Optimistic which means that the Wrapsite detects collisions during Save and protects the first User’s changes from being overwritten by the changes made by the second User.  Read more under Edit Wrap Definition above.
  • Wrap Header – A block of separately defined common content appears above the Wraps when they are shown in web browsers. You can select what content block to use here.
  • Printing – You can disable all printing from the Wrapsite, e.g. for security reasons.
  • Settings Dictionary – These settings customize the logo, header background color, and QR code color for the Wrapsite. Contact Client Services if you need help with these technical settings.
  • Displayed Roles – Wraps inherit Role permissions from their Wrapgroups. Tick the box for each Role you want to be selectable for Wrapgroups.
  • Assignable Roles Pool – If you delegate administration of a Workgroup to a local administrator, you have the option of delegating administration also of the User Roles that you select here. To delegate administration of a Role to the local admin of a particular Workgroup, you must make the Role assignable in this global setting and also select it in the Assignable Roles list for the particular Workgroup.