Before You Begin

This 15-minute tutorial shows you how to access Oracle Visual Builder Studio from Oracle Cloud Applications, create an extension, add an App UI that includes Oracle SaaS data, and publish the extension.

Background

Visual Builder Studio (or VB Studio, for short) gives you the power to customize Oracle Cloud Applications to suit your company's specific business needs. In fact, you'll have the exact same tools—VB Studio and Oracle Javascript Extension Toolkit (JET)—that Oracle developers use to create Oracle Cloud Applications in the first place, giving you an unprecedented level of power and control over your Oracle Cloud Apps ecosystem.

Extensions are what you use to deliver new capabilities into Oracle Cloud Applications. Those capabilities may take the form of customizations you make to the App's user interface, or your extension may include things like App UIs, to deliver new pages or resources to your Oracle Cloud Applications instance. An App UI is simply an application that includes a user interface component in the form of VB Studio pages and flows.

In this tutorial, we'll create an App UI that presents employee data from an Oracle SaaS service connection, then allows users to search for a specific employee.

What Do You Need?

  • Access to Oracle Cloud Applications
  • Access to Visual Builder Studio
  • A project that is set up for extensions. If you don't have a project available, you might need to create one.
  • A supported browser

Access Visual Builder Studio

In this step, we'll see how to access Visual Builder Studio from Oracle Cloud Applications.

  1. Make sure that VB Studio is set up to extend Oracle applications. See Set Up VB Studio to Extend Oracle Applications.
  2. Log in to Oracle Applications Cloud.
  3. From the Configuration section of the Navigator, choose Visual Builder:
    4. Description of images/vbsea_sec1_s3.png follows
    Description of the illustration vbsea_sec1_s3.png
  4. In VB Studio, select a project that's associated with the Oracle Cloud Application environment.
  5. In the project Workspaces Workspaces icon tab, click New and choose New Application Extension:
    6. Description of images/vbsea_sec1_s5.png follows
    Description of the illustration vbsea_sec1_s5.png
  6. In the Extension Name field, enter a name for the extension. The extension name must be unique, so you might want to use HCMSearch, prefaced by your initials. The Extension ID and Workspace name are automatically filled in, but you can change them if you'd like.
  7. In the Development Environment field, choose Development.
  8. In the Base Oracle Cloud Application field, choose None.
  9. In the Git Repository section, select Create a new repository, and add names for the repository and working branch:
    10. Description of images/vbsea_sec1_s9.png follows
    Description of the illustration vbsea_sec1_s9.png
  10. Click Create.

    VB Studio opens in the Designer, where you can begin creating your App UI. Your screen should look something like this:

    Description of images/vbsea_sec1_s10.png follows
    Description of the illustration vbsea_sec1_s10.png

Create a New App UI

Now we're going to start building a simple App UI that allows users to search for an employee, based on data that we'll get from Human Capital Management (HCM).

  1. In the App UIs App UI icon pane, click + App UI:
    2. Description of images/vbsea_sec2_s1.png follows
    Description of the illustration vbsea_sec2_s1.png
  2. In App UI Name, enter the name of the application, perhaps something like HCMSearch.

    The App UI ID is automatically filled in, but you can change it if you'd like.

  3. Click Create.
  4. In the App UIs pane, expand the main node, and click main-start to open the page in the Designer.
  5. In the Components palette, enter heading in the filter field to locate the Heading component, then drag and drop it onto the canvas. In the Heading's Properties pane, enter Employee Search in the Text field:
    6. Description of images/vbsea_sec2_s5.png follows
    Description of the illustration vbsea_sec2_s5.png
  6. In the Components palette, filter to find the Input Text component, then drag and drop it under the header on the canvas. Make sure you see the plus sign (+) before you drop the component, so you know you're working in a valid area:
    7. Description of images/vbsea_sec2_s6.png follows
    Description of the illustration vbsea_sec2_s6.png
  7. In the Properties pane Label Hint field, enter Emp Name. This will serve as placeholder text in the field.

    8. Now we're going to create a variable that we can map the input field to. This variable will hold the employee data that the user will be able to search.

  8. In the Properties pane, select the Data tab. Hover over the Value text and click the Select VariableSelect Variable icon icon next to fx.
  9. Click the Create Variable link next to Page:
    10. Description of images/vbsea_sec2_s9.png follows
    Description of the illustration vbsea_sec2_s9.png
  10. In the ID field, enter searchString and click Create.

Access Oracle SaaS Data

Below the input text field, we want to show a list of employees that the user can choose from. To do this, we need to establish a service connection to Oracle Human Capital Management (HCM) so we can get the data we need.

  1. Click Services Select Variable icon in the Navigator.
  2. In the Services pane, click + Service Connection:
    3. Description of vbsea_sec3_s2.png follows
    Description of the illustration vbsea_sec3_s2.png
  3. In the Select Source page of the Create Service Connection wizard, click Select from Catalog.
  4. In the Service Catalog, click the tile for Human Capital Management:
    5. Description of vbsea_sec3_s4.png follows
    Description of the illustration vbsea_sec3_s4.png
  5. In Create Service Connection search box, enter work, then select publicWorkers from the list:
    6. Description of vbsea_sec3_s5.png follows
    Description of the illustration vbsea_sec3_s5.png
  6. Click Create.

    7. Now we can use the service connection we just created to create the list of employees we want.

  7. Click App UIs App UI icon in the Navigator and select main-start.
  8. Select the Data tab in the Page Designer and expand Services and site_HCMSearch:hcmRest. Drag publicWorkers onto the page underneath the Input Text component:
    9. Description of vbsea_sec3_s8.png follows
    Description of the illustration vbsea_sec3_s8.png
  9. You can see that we have a list of options for presenting the data, and in this case we want to choose the second List item:
    10. Description of vbsea_sec3_s9.png follows
    Description of the illustration vbsea_sec3_s9.png
  10. In the Add Data wizard, accept the default template in the Select Template page and click Next:
    11. Description of vbsea_sec3_s10.png follows
    Description of the illustration vbsea_sec3_s10.png
  11. In the Bind Data page, the Endpoint Structure panel shows all the fields that are available for us to choose from in the publicWorkers object. Drag and drop each of these fields from this panel to the Item Template Fields section as specified, using the search field to help you locate them:
    • Default slot: DisplayName
    • Secondary slot: PhoneNumber
    • Tertiary slot: LocationTownOrCity
    Description of vbsea_sec3_s11.png follows
    Description of the illustration vbsea_sec3_s11.png
  12. Click Next.

Set Up Filtering

In this section, we're going to set up a filtering mechanism for our list, based on the display name of the employee. We want to compare each name to whatever the user enters as a search string, in order to find the proper match.

  1. In the Define Query page of the wizard, select filterCriterion from the Target panel.
  2. At the bottom of the page, click the Click to add condition link.
  3. Set up the condition by selecting the following:
    • Attribute: DisplayName (Select the DisplayName attribute that's not part of the assignments list.)
    • Operator: contains ($co)
    • Value: $variables.searchString
    4. Description of vbsea_sec4_s3.png follows
    Description of the illustration vbsea_sec4_s3.png
  4. Click Done, then click Finish.

Test and Publish the Application

We will first test the page to make sure it's working correctly, then we can publish the application. After the application builds in VB Studio, we can view the published version.

  1. To test your App UI, click the Preview Preview icon button.
  2. To filter the list, enter a search criteria, like the first name David:
    3. Description of vbsea_sec5_s2.png follows
    Description of the illustration vbsea_sec5_s2.png

    Now that you've confirmed the search is working, you're ready to publish your extension with its App UI.

  3. In your App UI, click the Publish button:
    4. Description of vbsea_sec5_s3.png follows
    Description of the illustration vbsea_sec5_s3.png
  4. In the Commit Message field, add a description of the changes, then click Publish Changes:
    5. Description of vbsea_sec5_s4.png follows
    Description of the illustration vbsea_sec5_s4.png
  5. If prompted, provide your user name and password for the development instance. These must be Oracle Cloud Application credentials, as opposed to Visual Builder Studio or SSO credentials:
    6. Description of vbsea_sec5_s5.png follows
    Description of the illustration vbsea_sec5_s5.png
  6. When the changes have finished publishing, click Close.

    7. Now let's check to see how our packaging and deployment jobs, which are part of the publishing action, are coming along.

  7. Click the left arrow in the upper left corner of the application to go back to the Project Home page.
  8. Click the Builds Environments icon tab to check the build jobs that package and deploy the extension to your development instance. If the build job is still running, you can view its progress in the Job Queue tab. It might take a few minutes for the build to start if an executor isn't immediately available.
    Description of vbsea_sec5_s8a.png follows
    Description of the illustration vbsea_sec5_s8a.png

    To view the sequence of build jobs, click the Pipelines tab, then select View Layout under the Actions Actions icon menu for the HCMSearch-Package and Deploy job.

    Description of vbsea_sec5_s8b.png follows
    Description of the illustration vbsea_sec5_s8b.png

  9. Click the Environments Environments icon tab in the Navigator and select the Deployments tab.
  10. In the Application Extensions section, expand the extension:
    11. Description of vbsea_sec5_s10.png follows
    Description of the illustration vbsea_sec5_s10.png
  11. Click Openopen icon next to your App UI to open it in a new browser tab.

Learn More

To learn more about extending App UIs, see Extending Oracle Cloud Applications With Visual Builder Studio.