Embed a Web App in an Oracle Cloud Application

You can edit an Oracle Cloud Application to embed your web app using Page Composer or Application Composer. For your embedded web app to work in an Oracle Cloud Application, you'll want to confirm that:

• Your Visual Builder instance is associated with Oracle Cloud Applications;
• Single Sign-On (SSO) is enabled;
• The authentication for your web app is using an Oracle Cloud Account.

Note:

Contact your service administrator or project owner if you are unsure about how your Visual Builder instance is configured.

Specifically, the Allow only secure applications to be created setting in the instance must be unchecked to prevent users from seeing this message: Refused to display 'https://idcs-domain.identity.oraclecloud.com/ui/v1/signin' in a frame because it set 'X-Frame-Options' to 'deny'.

When a user is logged in to an Oracle Cloud Application, the application provides the user's Oracle Cloud Account details for authentication when accessing the embedded web app, so the web app will appear in the application's page without requiring any additional login. This authentication only occurs when the user first accesses the embedded web app and may mean that the web app takes a long time to load. Subsequent accesses will be faster.

To add your web app to an Oracle Cloud Application, you'll need to:

1. Prepare your web app in Visual Builder;
2. Publish your web app;
3. Embed your web app using Page Composer or Application Composer.

   For more information on which one you will use with your Oracle Cloud Application, see Differences Between Using Page Composer and Application Composer in Configuring and Extending Applications.

Make Your Web App Ready for Embedding

Before embedding your app in an Oracle Cloud Application, you'll want to configure your web app settings to allow embedding, and modify your shell page to remove the app's default header and footer. You might also want to choose a theme for your application that matches the look and feel of the application where you are embedding it.

When embedding a web app, it is quite common to set up your web app so that the Cloud Application passes some values to the web app as parameters in the URL. The input parameters are usually assigned to app-scoped variables defined in your app. The variables need to have the Pass on URL option set in the Properties pane.

To get your app ready for embedding:

1. In your web app's Settings editor, open the Security tab and select Allow embedding in any application domain or Allow embedding in specified domains.
   
   
   Description of the illustration usecase-embed-embeddingpanel.png
   
   
2. If you chose Allow embedding in specified domains, enter your Oracle Cloud Application instance's domain (for example, fa-identifier.fa.ocs.oraclecloud.com. Make sure you also add the domain's IDCS host name (for example, idcs-identifier.identity.oraclecloud.com).
   
   
   Description of the illustration domains-example.png
   
   
   You can add multiple domain names where embedding is allowed, but typically only one IDCS host name is required.
3. If you want to change your app's theme, open the General tab and select the theme from the drop-down list in the General tab.
4. In the Navigator, expand Root Pages and open the shell page in the Code editor.
5. Delete the <header> and <footer> elements in the code.
   
   

   
   Description of the illustration usecase-embed-shellpage.png

   
   

   Your shell page should now only have <div> elements for the page, message notifications, and the content. In Design view, you can see that the app now only contains the core content.

6. When your app is ready to be embedded, stage and publish the app so that the app is accessible at a public URL.
7. Open the live app in your browser to confirm that the page renders correctly at the URL.
   When testing the URL, you might also want to test that passing your app parameter in the URL works correctly, for example, by including the variable name and some value in the URL (https://vbinstanceurl/.../appname/?VariableName=Value)
8. Copy the URL, and make a note of the app parameters you are using.
   You'll need to know the URL and the parameters when you embed the app using Application Composer or Page Composer.

Embed a Web App Using Page Composer

For Oracle Cloud Applications that you edit using Page Composer, you embed your web app by adding a Web Page component to a page and then specifying the app's URL and parameters. The following steps are high-level and are presented here to help you embed your web app in a page using Page Composer. For additional details, see Guideslines for Using Page Composer in Configuring and Extending Applications.

To embed an app using Page Composer:

1. Log in to the Oracle Cloud Application where you want to embed your app.
2. Open a sandbox with Page Composer enabled, if you haven't already.
3. In your Oracle Cloud Application, navigate to the page where you want to embed your web app content.
4. Open the Tools menu and select Page Composer.
   
   

   
   Description of the illustration usecase-embed-openpagecomposer.png

   
   

   Page Composer will appear in the menu if you're in sandbox which is configured to be edited using Page Composer.

   If you are using Application Composer, see the next topic.

5. In the Source view, open the Selector panel and select the area in the page where you want to embed your app. Click Edit in the popup menu to enter Edit mode.
6. Make sure the area is selected in the Selector panel, then click Add (+) in the panel's toolbar and add a Web Page component in the Add Content dialog. Click Close.
   
   

   
   Description of the illustration usecase-embed-addwebpage.png

   
   

   The area now contains the Web Page component.

7. In the Selector, right-click the new Web Page component and select Edit in the popup menu to open the Component Properties: Web Page dialog box.
8. Add a name and description for the new component.
9. In the Source field, open the dropdown list and select Expression Builder.
   If you are passing a variable to your web app as part of the URL, you'll need to use the Expression Editor to construct the URL.

   If you aren't going to pass a variable, you can paste the URL for your web app in the Source field.

10. In the Expression Editor dialog, select Choose a Value, and then select Binding Parameter in the dropdown list.
11. Select the binding parameter you want to use from the dropdown list.
12. Select Type a value or expression, then edit the expression in the text area to define the URL of your web app.

    The text area contains an expression fragment (<generated-expression>) generated for you based on the binding parameter you selected. It might look something like #{bindings.DisplayName.inputValue}. This is the value that will be passed to your web app.

    
    

    
    Description of the illustration usecase-embed-expression-editor.png

    
    
13. Prepend the URL of your web app to this expression in the text area.

    Your expression might look something like https://vbinstanceurl/.../appname/?VariableName=<generated-expression>. When you paste in the URL, make sure it includes ?VariableName= before the generated expression, where VariableName is the name your web app expects in the URL (for example, "OwnerName").

14. Click OK to close the Expression Editor dialog, then click OK to close the Component Properties dialog box.
15. Click Done to finish the Page Composer editing session.
16. Publish your sandbox after you've added the web page.

After closing the editing session, your web app content appears in the area in the page in the Oracle Cloud Application. The app is embedded in the page, and you can navigate to pages within the web app without leaving the Oracle Cloud Application page containing the web app. You can use your web app to display web app data in a page, and for example, to show a graph that rendered in the web app.

Embed a Web App Using Application Composer

For Oracle Cloud Applications that you edit using Application Composer, you embed your web app by adding a mashup to the application, for example, in a tab or a page. The following steps are high-level and are presented here to help you embed your web app in a page using Application Composer. For a detailed description of how to embed a web app, see the Overview of Mashups section in Configuring Applications Using Application Composer.

To embed a web app using Application Composer:

1. Log in to the Oracle Cloud Application where you want to embed your app.
2. Open a sandbox with Application Composer enabled, if you haven't already, and then open Application Composer.
3. Create a parameter-based mashup for the web application.

   If you want to pass any input parameters to your web app, you'll need to define the names of the parameters when you create the mashup. For example, if your web app is using an input variable named accountid (https://vbinstanceurl/.../appname/?accountid=SomeValue), you'll want to add accountid to the mashup.

   For more details on creating a parameter-based mashup, see Register Your Web Application in Configuring Applications Using Application Composer

   
   

   
   Description of the illustration usecase-embed-appcomposer-register.png

   
   
4. In Application Composer, locate the application page (for example, the Details page) where you want to embed the web app.

   If you specified any parameters in your mashup, you'll need to map the parameters to fields in your application. For example, you would map the Registry ID field to the accountid parameter you defined in the mashup if you wanted to use the Registry ID value as your web app's input parameter. For more on adding a mashup to a page, see Embed a Registered Web Application into Your Application Page in Configuring Applications Using Application Composer.

   
   

   
   Description of the illustration usecase-embed-appcomposer-mashup.png

   
   
5. Publish your sandbox after you've added the mashup to your application.