Configuration iframes

This topic explains how configuration iframes work within the app framework.

App are able to propagate 'save' and 'close' messages to the product in the app configuration and service configuration iframes. This communication is achieved via postMessage; the app will first postMessage to the AMS sandbox iframe, and AMS will then postMessage directly to it's parent window.

In this topic:

• Developing for iframes

  • Saving and closing iframes
• Sample code

Learn more by watching the video

Overview

Configuration iframes are required for two purposes:

• App configuration. This is the event where apps are configured from an CX product's app catalog. App users will click a Configure button to configure the app to be used.
• Service configuration. This is the event where services are configured from within an CX product (for example, a canvas) to be used. Users may drag a service onto a canvas, and then click to configure that service with the values to send and receive.

Developing for iframes

Saving and closing iframes

The app can postMessage directly to the AMS iframe to save and close the iframe. The postMessage body must include the following fields for AMS to send the message to the product:

• amsAction

• notifyProduct

  Possible values are close or save.

• status

  Possible values are approved or refused.

In addition to these fields, the app may choose to include a requestId or payload, which are recommended but optional.

Example 'Close' postMessage : App to AMS

{
    "amsAction":"notifyProduct",
    "notifyProduct": "close",
    "status": "approved",
    "requestId": "uniqueUuid",
    "payload": null
}					

Example 'Save' postMessage : App to AMS

{
    "amsAction":"notifyProduct",
    "notifyProduct": "save",
    "status": "refused",
    "requestId": "uniqueUuid",
    "payload": null
}					

If the request is successful, after the receiving the postMessage from the App, AMS will then postMessage directly to its parent window (the product iframe).

Sample code

In the sample app, the service instance configuration page embeds a 'close' button if it is being rendered in an iframe:

For the sake of simplicity, the 'Close' button binds to the 'closeForm' function. The 'Save' button binds to the 'saveForm' function

// configureInstance.html embedded js
function closeForm() {
    // perform any logic required to close here, then postMessage up to AMS, requesting product to close iframe
    statusMessageCommunication.postMessageCloseStatus("approved");
}
...
 
function saveForm() {
    var form = $("#configuration-form");
 
    // Get json from form fields with jquery magic
    var jsonObject = {};
    $(form).serializeArray().forEach(function(item){
        jsonObject[item.name] = item.value;
    });
 
    // Submit json to AMS
    $(".result").html("Saving...");
    appConfigSubmitter.sendRequest(jsonObject, function(data) {
        if(data.httpStatusCode === 200) {
            $(".result").html("The install is successfully configured.");
            statusMessageCommunication.postMessageSaveStatus("approved");
        } else {
            $(".result").html("Failure save configuration: " + data.payload);
            statusMessageCommunication.postMessageSaveStatus("refused");
        }
        console.log(data);
    });
}					

// configure.js
class BaseAmsCommunication {
    sendMessage(message) {
        window.parent.postMessage(message,'*');
    }
    ...
}
  
class AmsAppNotifyProductCommunication extends BaseAmsCommunication{
 
    constructor() {
        super();
        this.amsAction = "notifyProduct";
    }
 
    postMessageSaveStatus(status) {
        super.sendMessage({"amsAction":"notifyProduct", "requestId": "notifyProduct", "notifyProduct": "save", "status": status});
    }
 
    postMessageCloseStatus(status) {
        super.sendMessage({"amsAction":"notifyProduct", "requestId": "notifyProduct", "notifyProduct": "close", "status": status});
    }
    ...
}					

In this use case, the app will send a 'save' postMessage with a status of 'approved' on a successful save, and a status of 'refused' upon a failed save.

If the 'close' button is clicked, the app will send a 'close' postMessage, indicating the app is ready to close to the iframe. AMS will then directly postMessage to it's parent iframe the following postMessage body:

Sample App 'Close' postMessage : App to AMS

{
    "amsAction":"notifyProduct",
    "notifyProduct": "close",
    "status": "approved",
    "requestId": "uniqueUuid"
}					

Hereafter, the product should listen for postMessages coming directly from the AMS iframe, and inspect the fields of each postMessage body, to determine the current state of the configuration iframe.

Note: From the app developer perspective, it is recommended that any necessary cleanup and/or validation is performed by the app prior to sending the 'close' message.

Learn more

App Configuration

Service Lifecycle

Developer topics