Linking to Wrap instances

This help page documents how to create hyperlinks to Wraps. It also describes useful options like openmode.

A link to a Wrap may look like this:

https://toc.live.excelwraps.com/Wraps/RedeliveryCost_WeeklyReport?year=2021&month=2&day=14&fleet=cl321&reid=1&openmode=fast

The link has several basic components:

  • It designates the Wrapsite, in this case toc.live.excelwraps.com.
  • It identifies itself as a Wraps link to transactional content. Links to reports are MyWraps links.
  • It designates the Wrap, in this case RedeliveryCost_WeeklyReport.
  • It provides the value for the Unique Keys – year, month, day, fleet, and reid – that together designate a single instance of the Wrap.
  • It can set options like the performance-related openmode, which obtains historical database results faster and with less resource consumption.

Access is governed by the permissions model

All Users may not have full access to all instances. The ExcelWraps Permissions Model makes it easy to control each user’s ability to create, edit and/or read Wrap instances.

  • If you provide a link to a non-existing instance of a Wrap, and the current User has Create permission, a new instance is automatically created with the requested Unique Key. Users without Create permission instead get a Not Found error message.
  • If you link to an existing instance and the current User only has Read permission, the instance is opened in a safe, read-only mode.
  • If you link to an instance for which the current User has no permission whatsoever, no access is granted and an Access Denied error message is issued.

If you need help linking to your Wraps and their instances, please don’t hesitate to contact our client services team.

The Openmode parameter

Performance considerations

openmode=automatic

This is the default option. It identifies the instances you link to, refreshes all the WrapLinks, WraplinkAggregates, and WrapLinkLists for Wraps that are not frozen, and returns the updated values.

This mode takes the longest time to set up, because of the cascading database operations necessary to acquire the current value for all the linked fields, all the values they depend on, and so on. If you don’t need the most recent changes, you should consider using openmode=fast instead.

openmode=fast

When a Wrap only provides historical information, e.g. as a dashboard, you should always consider appending &openmode=fast to the link to its instances. This greatly increases performance.

  • The fast open mode uses the most recently cached values for the linked values in the requested instances.
  • The automatic open mode spends considerable resources acquiring the most recent live values for each link, which in turn may require recalculation of other instances in a cascading fashion.

For live instances, openmode=fast is noticeably faster than a “full” open, in particular when many instances are involved.

The automatic open mode may generate different results than the fast open mode for modified live instances. For frozen and unmodified instances, the same results are returned by both modes. If you access data that doesn’t change significantly between recalculations, you should use the fast open mode.

Accessing the PDF instead of the database

openmode=pdf

If you want to link to the PDF file for a Wrap, you append &openmode=pdf to the link. This will either open an existing pdf generated from the contents of the Wrap, or report that there isn’t one. In the latter case, a background job to generate the PDF file is also initiated. This option can only be used when you provide a unique key that matches exactly one instance. Read more on the help page on how to automatically print Wraps to PDF files.

openmode=checkpdf

If you want to link to the PDF file for a Wrap, without requesting one to be generated, you can append &openmode=checkpdf to the link. This will either open an existing PDF, or just report that there isn’t one. This option can only be used when you provide a unique key that matches exactly one Wrap.