Canvas: Intro to Advanced Integration URLs

Last Updated -

iFrame Integration URLs: iFrame and Canvas

Two new options have been added to the “Open Location” options list.   Both of these new options only apply to Next Gen Agent and are directly related to the new Case Layouts feature in Next Gen.  The “Canvas iFrame” option is only available on Desk instances at the Pro and Business Plus levels.

When an integration URL’s Open Location is set to either the ‘Standard iFrame’ or the ‘Canvas iFrame’ setting,  it will not appear in the list of integration URLs in either Classic (“Info Links”) or Next Gen Agent (link icon).  Instead, it will appear as an “Integrations” component in the Next Gen Case Layout drag & drop editor.  When dragged onto a case layout, an iFrame is added to to the layout which loads the integration URL.  You can read more about Next Gen Case Layouts in this support article.

Standard and Canvas iFrame integration URLs can be dynamic and include variables from the Liquid object model just like any other integration URL.

  • All accounts can have unlimited Standard iFrame integration URLs. 
  • Pro plan accounts can have one Canvas iFrame integration URL. 
  • Business Plus accounts can have unlimited Canvas iFrame integation URLs.

If you aren’t sure what Canvas is, you can learn more about it in this developer document. In short, it is a development platform that enables customization of the Next Gen Agent Desktop.  When a Canvas iFrame is put on a Case Layout, the page in the iFrame is able to talk to via Javascript.

Standard iFrames, in contrast, are static windows into other pages (the integration URL) with no communication between and the page rendered in the iFrame. Now let's create a Canvas iFrame.

Create a Canvas iFrame

  1. Go to Admin > Cases >Integration URLs.
  2. Select + Integration URL.

  1. In the Edit Integration URL window, add the 'Name' and 'Description' of the Integration URL.
  2. Under 'Open Location,' create an integration URL that opens as a 'Canvas iFrame.' The integration URL is the address of the app you have developed and are hosting somewhere. It will be applied at the SRC of the Canvas iFrame.
  3. Enable the URL via the toggle bar.
  4. Click 'Update.'

Note: The 'Shared key' is a randomly generated authentication string that communicates with the third party vendor. System administrators can reset this at their discretion.

  1. To assign permissions, go to: Admin>Cases>Next Gen Case Layouts.
  2. Once the integration URL is created, it will show up as an Integration component in the Next Gen Case Layout drag & drop editor. Simply drag it from the right column over onto the Case Layout and drop it where you would like it to display. 

  1. Once the Canvas iFrame is added to the Case Layout, assign the Case Layout to Users or Groups.
  2. The assigned Users or Groups can now see the Canvas iFrame (e.g., Location) in a ticket.

Pro Tips

Here is some helpful advice for developing and implementing your Canvas solutions.

Create a Test and Development Case Layout

As you or your developers are developing the application that will be hosted somewhere and run inside the Canvas iFrame, you will most likely want to test it and see how it’s working before rolling it out to all of your agents.

Create a new Case Layout that you will only assign to yourself, the developers and a few trusted testers, and put the in-progress Canvas iFrame on that Case Layout. This way you can control the rollout of the functionality, but still see it in action.

You can even go a step further and have your account executive set you up with a development sandbox environment. Doing the development on a Case Layout inside the sandbox is safer because none of your production data will be at risk during the development of the application.

Use the Context Payload in the Signed Post Request

When you create the Canvas iFrame integration URL, the URL itself can have dynamic variables added via the Liquid object model that Desk provides - this is the same for all Integration URLs. You are welcome to use those.

However, the signed post request we send when requesting your application URL has a payload of context information (in encoded JSON format) that includes all of the information available via Liquid and more. Instead of adding variables to your URL, just decode the payload in the POST Request Header and use the information we are already sending you.

More information about the payload and Canvas can be found in the Canvas Developer’s Guide.