Create an IFrame

IFrames allow you to embed content from a third-party into your Coupa instance. There are two types of IFrame apps: 

• Floating IFrames: IFrame is persistant and is located at the botton right or whichever page the user navigates to. When configuring an IFrame, Location is set to Floating. See Floating IFrames below. 

• Embedded IFrames: IFrame is embedded in a designated page. When configuring an IFrame, Location is set to a specific page.

Floating IFrames

IFrames include a type of floating IFrame that appears on every page in Coupa core. With floating IFrames, Coupa admins can now add their third-party tools like chat or other help widgets for every page in Coupa their users can access. Users don't have to leave Coupa while they get help from your IT or Support team.

Coupa places a small floating IFrame tab at the bottom right of core web UI. The tab doesn't stick to a page, but follows the user wherever they go in Coupa. The data in the tab also follows the user and won't lose any info if the user clicks away. When the user clicks the small tab, the tab opens to reveal the chat client or help widget the admin has configured. Floating IFrames that allow for expanding and collapsing include an interactive button to expand and collapse the window.

Create a floating IFrame

Create a floating IFrame using these steps. Admins can create up to three floating IFrames that display next to each other at the bottom right of the window, moving left with each new tab. 

1. Navigate to Setup > IFrames and Panels and click Create.
2. Set Location to Floating, and populate the URL.
3. Set the Client ID field. This is a unique ID used by the third party to ensure it is communicating with the correct Coupa Embedded App. It can be any unique string. Floating IFrames cannot have the same Client ID.
4. Populate the Descriptor field. This is JSON data that includes parameters and data to share with the third-party. For example:

   {
      "properties": {
         "app_key": {
            "type": "string"
         },
         "app_secret": {
            "type": "string"
         }
      }
   }

   In the example above, there are two custom properties,app_key andapp_secret, both of type string. Once added to the Descriptor field, the properties you create are added to the App Properties section.

5. Set the Application URL. This is the URL of the third party to be displayed in the Embedded App.
6. Click Save. When you reopen the IFrame record, you can add values to the properties you added to the App Properties section. 

To create a demo floating IFrame, enter these field values. This creates a sample IFrame with a button to expand and collapse the window. 

• Application URL: https://app-bridge-example-app.herokuapp.com/
• Client ID: 12345

Exchange data between floating IFrame and chatbot

Third parties can communicate with Coupa using the Javascript Postmessage API.  In this example, the user sets the app_secret property name with value 123456.

The code below provides the third party with access to this Embedded App.

// A function to send a postmessage call from your chatbot to Coupa Core and get the property value
const getSecret = () => {
  const propertyName = "app_secret";
  window.parent.postMessage(
    {
      action: "getSecret", // Message type.
      client_id: "Client ID for the floating Iframe",
      iframe_id: "Iframe ID for the floating Iframe",
      data: {
        key: "app_secret" // Property name you want to get from Floating Iframe. app_secret in this case.
      }
    }, "*"
  );
}

// This is the listener event which will listen to the incomming postmessage events
// from Coupahost to your chatbot.
window.addEventListener("message", function(event){
  var eventData = event.data;
  switch(eventData.action) {
    case "returnSecret":
      console.log(eventData.data) // This will print the property value on browser's console
      break;
  }
});

getSecret(); // Call to trigger the postmessage call to fetch the secret from Coupa core.

Resize a floating IFrame

You can resize floating IFrames using the Javascript Postmessage API.  For example:

// A function to send a postmessage call from your chatbot to Coupa Core to resize.
function resize(options = {}){
  window.parent.postMessage(
    {
      action: "resize",
      client_id: "Client id for the floating iframe",
      iframe_id: "IFrame id for the floating iframe",
      data: {
        height: 300, // height in px
        width: 300, // width in px
        initial: options.initial // Set this to true at the time of page load, false otherwise
      }
    }, "*" // substitute * with the coupahost url for enhanced security
  );
}

resize({ initial: true }) // Call this function with initial: true at the time of page reload.
resize({ initial: false }) // Call this function with initial: false at the time of button click to forcefully resize.

In this example, the parameters are defined as follows: 

• client_id: Same as the Client ID configured as the floating IFrame side.
• Iframe_id: IFrame ID of the floating IFrame you created. You can obtain this value from the IFrame URL.

The code below fetches the Embedded App ID for the third party:

// At your chatbot side, below code will help you get the Iframe ID.
let urlParams = new URLSearchParams(document.location.search);
urlParams.get("floating_iframe_id") // gets iframe id
urlParams.get("coupahost") // gets coupahost which can be used to enhance the postmessage security

Parameters

• height : Height you want the IFrame to be in px.
• width : Width you want the IFrame to be in px.
• initial : The initial flag can be either true/false:
  • True: To save and apply the most recent size of your IFrame, pass initial: true. For example, if your IFrame is 300 x 300 and you reload the page, then the system maintains the same size of the IFrame after the page reload. If there is no recent size and your chatbot is being loaded for the first time, the system takes the passed height and width for the resize event.
  • False: To resize an IFrame on button click, pass initial: false. This forcefully resizes the IFrame to the passed height and width regardless of the last saved IFrame size.

Size limits

There is a size limit up to which you can resize your IFrame.

Maximum Limits

• MAX_IFRAME_HEIGHT = 600px
• MAX_IFRAME_WIDTH = 565px

Minimum Limits

• MIN_IFRAME_HEIGHT = 20px
• MIN_IFRAME_WIDTH = 20px

Embedded IFrames

Embed IFrames anywhere Coupa supports panel apps, and provide specific Coupa attributes to your IFrame callout query. Embedded apps add context to specific pages like the homepage, supplier page, shopping cart, etc.  

Embed an IFrame

1. Navigate to Setup > Platform > iFrames and Panels.
2. Click Create and choose Create New iFrame 
3. In the Location  dropdown menu, specify the location of the app. If you leave the slot field blank, it won't appear on any specific page, and you'll need to create a menu item for the IFrame app, just like before. If you choose a slot, the Open In New Window option disappears.

Available locations

Coupa supports the following locations:

IFrame app query strings

Because IFrame apps call out to an external website or service, Coupa adds some query parameters to the Application URL. You can use these fields to identify the user and provide a personalized experience for them.

Considerations

• When you create an IFrame, the application creates a new permission and associated controller on the Custom Roles page. 
• Only HTTPS protocol is supported for IFrame apps in Coupa
• Customer to maintain an SSO or proper security constraints to their IFrame application
• Since an IFrame leverages a third party application data/content flow cannot be controlled on Coupa side. This can increase the risk of having a potential vulnerability in the application or simply having to deal with a bad user experience (like a video auto-play). It is recommended that customers restrict the IFrame capabilities to the needs of their users.
• Not all applications support the IFrame capabilities, customers must review to make sure that their application allows IFrames in order to use it in Coupa
  • Customers should also ensure the web browsers they use support IFrames
• Customer application pages shouldn't take longer times to load as it can affect user performance/experience
• If a third party application is sending an "X-Frame-Options: SAMEORIGIN" response header, this option prevents the web browser from displaying IFrames that are not hosted on the same domain as the parent page