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. Read more about pre-filling wrap fields.
  • It can set options like the performance-related openmode, which obtains historical database results faster and with less resource consumption, and overridefrozen, which makes it possible to recalculate frozen wraps. Read more below.

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.

The overridefrozen parameter

After a wrap has been frozen, ExcelWraps will normally never change it again. The WrapLinks and WraplinkAggregates it contains retain the values they had when the wrap was frozen. A frozen wrap is never recalculated.

If, during the early development of a wrap, you find that you would like already frozen wraps to be recalculated using an updated version of the wrap template, you can use the overridefrozen parameter.

&overridefrozen=true

When you open a frozen wrap with the above parameter in the link, the wrap will be recalculated using the most recent version of the wrap template before it opens on the screen. Press Save to save the recalculated values.

If recalculation would invalidate any previously captured signatures we would recommend rolling out a completely new wrap altogether. As always, feel free to contact Client Services if you need help.

The OnBehalfOf parameter

An Admin user can perform activities on behalf of another user. This ensures that the LastModificationUserName refers to the right user, and that the events are logged in the Audit trail as having been initiated by this user.

If you want to create a new wrap on behalf of another user, making that user the owner of the new wrap, you should instead use the createdby parameter in a Wraplink.

Example

https://selenium.development.excelwraps.com/Wraps/WrapOne?yourname=brian&subid=1&onbehalfof=otisredding

The WrapOne wrap will be opened. If a new version is saved, the LastModificationUserName will be set to otisredding. All events occurring as part of running the wrap are logged in the audit log for the otisredding user.