Proxies

An Embedded App configuration maps a configurable URL label within Experience Cloud to a web application running on a configurable service URL. Experience Cloud acts as a proxy or broker between the user's browser and the web application.

Experience Cloud provides two proxy mechanisms: a theming proxy and a passthrough proxy. The configuration of an embedded application is shared across the two proxy mechanisms. That is, for any given configuration, you can access backend services using either mechanism.

Theming Proxy

The theming proxy mechanism allows for theming of HTML content from backend services. It is invoked by calling a URL that specifies the embeddedApp.do resource with a label query parameter. 

For example: https://yourinstance.medallia.com/yourcompany/embeddedApp.do?label=app1&customParameter1=someValue.

Use this proxy mechanism for user interface access and simple web applications.

Passthrough proxy

The passthrough proxy mechanism allows for more advanced control of communications to backend services. It is invoked by calling a URL that specifies the eaproxy resource path.

For example: https://yourinstance.medallia.com/yourcompany/eaproxy/app1/api/v1/object?customParameter1=someValue.

Use this proxy mechanism for:

• Rich web applications
• RESTful API access to backend services
• AJAX requests
• Form POSTs

Request headers

Experience Cloud passes request headers to backend services, as listed in the table below. Experience Cloud does not forward any request headers from the user agent's original request to backend services.

Express-Api-Token

Express-Base-Url

Express-Company

Express-Role-Name

Express-Embeddedapp-Url

Express-Viewstate

Express-Optionbox-Filters

Express-Shared-Secret

Express-Username

Request parameters

Query parameters from the original request parameters are passed from the browser to the backend services, with the mechanism differing based on the request method.

Proxied GET requests to backend services include:

• All query parameters specified in the AppUrl string
• Any query parameters from the browser made to the embeddedApp.do endpoint where the query parameter starts with ea_. That  prefix is required for parameters passed in a GET request from the browser so there is a differentiation mechanism with AppUrl query string parameters.

Proxied POST requests to backend services include:

• All query parameters specified in the AppUrl string
• Any query parameters (regardless of name) and form data from the browser, both encoded as form data

Themed content in responses

By default, Experience Cloud assumes the backend service is returning an HTML snippet that should be wrapped in the overall Experience Cloud theme. Medallia recommends that the app return a <div>...</div> structure , with all content existing inside.

Raw content in responses

Sometimes it is desirable to shed the HTML wrapping that Experience Cloud provides, thereby returning only the response body from the custom web application. For example, if you use AJAX in the front end of your embedded application, you might want to make a request that receives data in JSON format. For this use case, use the eaproxy mechanism.

Configuring an embedded application

This procedure assumes that you have already created the application you want to embed in your Experience Cloud instance.

1. Open the Reporting > Reports > Embedded Apps screen.
2. Click New.
3. Enter a Label for the application.The label is used when the URL path ends in embeddedApp.do. For example, if the Express URL  https://express.medallia.com/ess/embeddedApp.do?label=test1  opens the embedded application with the label test1.
4. Enter a Name. The name is not exposed to users, and is used only to identify the embedded application when assigning it to a subtab in report navigation. For more information about making embedded applications available to users on a subtab, see  Navigation.
5. Optionally, enter a Description to add notes about the application.
6. Enter an AppURL, the fully-qualified URL Experience Cloud uses when forwarding requests to backend services. Other parameters are passed from the browser, as described in Request parameters, above.
7. If you plan to make the application available on a subtab in report navigation, turn on the WebMenu property.
8. If you want to include an Option Box on the subtab displaying the application, configure what filtering options are available to users:
   1. Turn on the EnableOptionbox property.
   2. In the MemberEmbeddedAppOptionboxPlugins property choose the filter plugins you want to be available by moving them to the right-side box.
9. If you want to grant access to the application for individual users as well as roles, turn on the Make all users available for MemberRoles property.
10. Click Save.
11. In the MemberRoles property, choose which roles (and users if they are listed) can use the application, and then click Save.
12. If you want to make the application available to users on a subtab in report navigation, assign it to a subtab as described in Navigation.

Properties on the Embedded Apps screen

You can set the following properties on the Reporting > Reports > Embedded Apps screen.

Label

The unique identifier for the Embedded App configuration. The label is used when the URL path ends in embeddedApp.do. For example, if the Express URL is https://express.medallia.com/ess/embeddedApp.do?label=test1 then Express uses the Embedded App configuration whose label is test1. All traffic that passes through the proxy mechanisms must be tagged with the label.

Name

The name appears in Medallia Admin Suite reporting only, enabling you to asign the Embedded App configuration to a subtab in report navigation if the WebMenu property is turned on. The name is not exposed to end users.

Description

A free-form text field that gives you a place to document the purpose of the Embedded App configuration.

AppUrl

Query parameters from the original request parameters are passed from the browser to the backend services, with the mechanism differing based on the request method.

Proxied GET requests to backend services include:

• All query parameters specified in the AppUrl string
• Any query parameters from the browser made to the embeddedApp.do endpoint where the query parameter starts with ea_. The ea_ prefix is required for parameters passed in a GET request from the browser so there is a differentiation mechanism with AppUrl query string parameters.

Proxied POST requests to backend services include:

• All query parameters specified in the AppUrl string
• Any query parameters (regardless of name) and form data from the browser, both encoded as form data

SharedSecret

A hex-encoded, static 128-bit randomly-generated number passed as a request header to backend services, which can validate this value to ensure that the request it is handling is from an expected Experience Cloud instance. To create a new shared secret, turn on the Confirm property and then click NewSharedSecret.

Note: Generating a new shared secret is an irreversible operation. If a backend service uses the shared secret for validation, only generate a new shared secret if you are prepared to update the backend service to expect the new shared secret. Failure to update the backend service may cause the backend service to stop responding to requests as expected.

Created

The creation time of the Embedded App configuration.

Make all users available for MemberRoles

When turned on, the roles available for the Embedded App will include all single users. You must save the Embedded App before a change to this property takes effect. If you have many user records, turning on this property can slow the performance of the Embedded Apps screen.

WebMenu

When turned on, the Embedded App configuration is available to be assigned to a subtab in report navigation. For more information, see Navigation.

When turned off, users can still access the embedded application directly if they know the URL. They can also be routed to the application by another embedded application.

EnableOptionbox

When turned on, adds the Option Box to the report screen showing the embedded application to users. This property is only applicable when the WebMenu property is turned on, since only those applications can be displayed on a subtab in report navigation.

MemberEmbeddedAppOptionboxPlugins

Determines which filter options are available for the embedded application in reporting. This property is only applicable when the EnableOptionBox property is turned on.

MemberRoles

Roles move to the right-side box have access to the URL of the embedded application. If you need to grant access to specific users, first turn on the Make all users available for MemberRoles property, and then move users to the right-side box.

TranslationExplanation

If you are translating your instance, use this property to enter notes about the application for the translator. For more information about translating reports and surveys, see  Localization.