Creating Business Objects

You can use the Data Designer to create and define new custom business objects in your application.

You use custom business objects to store data that is not provided by an external service. When you create custom business objects you specify each of the fields that your application needs. As you develop your application you can modify your business objects to add and modify fields as needed. You can create business objects in the Page Designer or in the Data Designer.

The business objects in your application are defined in the database schema. When you want to create and modify business objects and fields you can use the Data Designer to modify the schema of your development database.

To create a new custom business object in the Data Designer:
  1. Open Business Objects in the Data Designer page.
  2. Select Development in the drop-down list.

    Description of data-designer-db-dropdown1.png follows
    Description of the illustration data-designer-db-dropdown1.png
    You can only create new business objects in your Development environment. Business objects are created on the Staging database when you stage the application and update the Staging database schema. See Managing Data During the Development Lifecycle.
  3. Click New Business Object and select Custom Object in the drop-down list.
  4. Type a name for the new object. Click OK.
    When you click OK the object is created and general details about the new object are displayed in the Overview tab.
  5. Open the Fields tab of the new object.

    Description of data-designer-fieldstab.png follows
    Description of the illustration data-designer-fieldstab.png
    The Fields tab displays all the fields in the object. Each new business object has some default fields that are generated automatically when you create the object.
  6. Click New Field.

    Description of data-designer-newfield.png follows
    Description of the illustration data-designer-newfield.png
    The New Field dialog enables you to specify the details of the new field, such as its display label, field name and data type.
  7. Type the Display Label for the field.
    The Display Label is used to identify the field in the UI components of your application. A Field Name is automatically generated based on the Display Label, but you can modify the Field Name according to your requirements. The Field Name identifies the field in the database schema.
  8. Select a Field Data Type. Click OK.
    Depending on the Data Type that you select, you might need to provide additional details, for example, if the field is a lookup or references another business object. You can edit the fields later.
  9. Create any additional fields that you want in your business object.
After the object is created you can use the Data Designer to edit the fields and add any rules, create child objects or related objects. You can add data in the Data tab of the Data Designer, by importing data from a file in the Data Manager or with forms that you build using the Page Designer. See Editing Fields of Business Objects.

Creating a Business Object from an External Service

Create connections and business objects for external services using the Add Service wizard in the Data Designer.

To use a REST service provided by your associated Oracle Cloud services or other REST services in your application you need to create a business object that exposes the service. The Add Service wizard enables you to choose a service in your catalog and select the resources that you want to make available as business objects in your application.

To create a business object for a service:

  1. Open Business Objects in the Data Designer page.
    You can open the Add Service wizard from the Business Objects page or the Services page.
  2. Click New Business Object and select Select from External Service in the drop-down list.
    Alternatively, from the Services tab you can click Add Service .

    Note:

    In the Business Objects page, the Development database must be selected in the database drop-down list.
  3. Select a service in the catalog. Click Next.
    The catalog lists the services that are accessible to you in your Identity Domain. You can use the filters to limit the number of services that are listed.
    Description of services-wizard-catalog.png follows
    Description of the illustration services-wizard-catalog.png

    Note:

    In the Catalog step you can click Add a new service to add a connection to an Oracle ADFm REST Service. To add the service you will need to provide an ADFm REST Services Descriptor Document or the URL of the ADFm REST service and authorization credentials.
  4. In the Parameters step, confirm the version and URL of the service you want to use.
  5. In the Business Objects step, select the checkbox for each resource that you want to use in your application. Click Next to specify the data fields to use in the business object.

    Description of services-wizard-objects.png follows
    Description of the illustration services-wizard-objects.png
    The left column contains a list of resources provided by the service. You can select a resource to view the name and description of the resource. For some services, you will not need to create business objects for every available resource.

    Note:

    A business object will be created for each resource that you select. However, only top-level resources will be available as business objects in the Page Designer because child objects and related objects require the parent or referencing object.
  6. In the Fields step, specify the fields that will be available in the business object by dragging fields from the Available Fields column into the Selected Fields column. You can do this for each business object. Click Next.

    Description of services-wizard-fields.png follows
    Description of the illustration services-wizard-fields.png
    You can customize the fields in each business object. When you select a business object you see a list of the available fields provided by the business object. By default the Selected Fields list contains all the fields required by the business object and some optional recommended fields. For fields that you do not need in your business object, you can remove the fields by clicking X next to the field name in the Selected Fields list. Click the field name in the list to expand the item and modify the Default Label and to add a description.
  7. Confirm the authentication credentials for the service. Click Next to test the data provided by the selected service or click Finish to complete the wizard and create the business objects.
  8. Optional: In the Test step, select a resource to verify that the resources and fields you selected provide the data that you expect.

    Description of services-wizard-test.png follows
    Description of the illustration services-wizard-test.png
    A GET is called on the selected resource when you select the resource and the fields in the table are populated with data retrieved from the service.
  9. Click Finish.
New business objects for the selected resources are created when you finish the wizard. In the left column of the Services page you can view a list of the external services providing business objects for your application. You can modify the business objects provided by the services in the Business Objects page.

Creating Custom Connectors for REST Services

Create custom business object providers to connect to external web services and expose them as business objects.

You can expose an external web service as a business object by creating a custom business object provider (BOP). A custom BOP is an application extension that provides a connection to a REST web service. If a BOP for the service is not available as an extension, you can create the extension using a business object provider template in the Extensions page and then editing the source code and metadata for the BOP. The sources for the BOP can be edited in the Sources tab, or you can export the sources to edit them in your local editor and import them. After you create your custom BOP you can select it in the Service Catalog and configure the business object for your application. After a service is exposed as a business object, you can use it in your application and bind it to components in your application.

Several business object providers are included by default in the Service Catalog for connecting to Fusion Applications web services. Custom BOPs provide a way to connect to services that are not already included in the catalog or that don't use one of the valid supported specifications (Oracle REST, ADFm REST). Custom BOPs can also be used to provide access to aspects of a REST service that are not otherwise available for declarative consumption.

Note:

Business object providers can be shared between applications in the tenant space like other extensions. See Using a Shared Business Object Provider.
To create a custom business object provider:
  1. Open Extensions in Application Settings and select the Business Objects Provider tab.
  2. Click New Business Objects Provider and select Create New.
  3. In the Create New Extension dialog box, type a Display Name and Extension ID. Click Template.
  4. Select the Create Empty Extension template. Click OK.
    The Available Templates page provides several different templates: an empty extension, a custom BOP showcase, a JIRA REST BOP example, and a simple REST BOP example. The non-empty templates show different ways to use Visual Builder APIs.
    Description of extensions-bop-template.png follows
    Description of the illustration extensions-bop-template.png
    When you click OK the new custom BOP is added to the list of BOPs in the Business Object Providers tab. When you select a BOP in the list you see details such as the Display Name and description of the BOP in the Overview tab.
    Description of extensions-bop-list.png follows
    Description of the illustration extensions-bop-list.png
    The Sources tab contains a Resource Browser that displays a directory tree with all the source files for the BOP. You can edit the source files by selecting the file in the directory tree and editing the file in the editor. If you prefer to edit the source files in a different editor you can use the Export button in the Sources tab to download the BOP sources as an archive.
    Description of extensions-bop-source.png follows
    Description of the illustration extensions-bop-source.png
    If you edit the sources in a local editor, you can import the edited sources as a zip archive. To import the archive, open Resource Browser in Application Settings and import the archive into the extensions folder.
  5. When you are finished creating your custom BOP, open Services in the Data Designer and click Add Service to open the Service Catalog.
    The Services page displays a list of all the services you have already added.
    Description of extensions-bop-addservice.png follows
    Description of the illustration extensions-bop-addservice.png
  6. Select your custom BOP from the list of available connectors to services. Click Next and step through the wizard to create the business objects for the service.
    You can filter and sort the list of services available in the catalog to help locate your custom BOP.
    Description of extensions-bop-catalog.png follows
    Description of the illustration extensions-bop-catalog.png
After adding the service, the new service will be listed on the Services page and the business objects exposing the service that you added will be displayed in the list on the Business Objects page. In the Page Designer you can now add a component such as a table and bind it to the new business objects.

Modifying the Business Objects Provided by a Service

After you have added business objects for a service, use the Services page to create additional business objects from the service and the Business Objects page to add more fields to existing business objects.

If you need to modify an existing business object to add fields from the service or custom fields, you use the Business Objects page to add new fields. From the Services page you can open the Business Objects page for any of the existing business objects provided by the service. You can edit the properties of the fields after adding them to the business object. See Editing Fields of Business Objects.

To add fields for an existing business object:

  1. Open Services in the Data Designer.
  2. Select the service that you want to modify.

    Description of data-designer-services-overview.png follows
    Description of the illustration data-designer-services-overview.png
    The right panel contains tabs that enable you to view details about the selected service, including the business objects and authentication details..
  3. Open the Business Objects tab for the service.
    The Business Objects tab displays a list of the business objects provided by the service that are available in your application.
    Description of data-designer-services-objects.png follows
    Description of the illustration data-designer-services-objects.png
  4. Click the business object to open the Business Objects page.
  5. Open the Fields tab for the business object.
    The Fields tab displays the current list of fields defined in the business object. The Source column indicates if the field is an external service field or a custom field.
  6. Click New Field and choose Select from Service in the menu.
    Choose Select from Service to open a dialog box that lists the available fields. The details for fields created from a service are determined by the service, but you can edit the details in the Fields tab.
    Description of data-designer-objects-newfield.png follows
    Description of the illustration data-designer-objects-newfield.png
    You can choose Custom if you want to create a custom field in the business object. Custom fields are defined in the same way that you define fields in custom business objects, for example, by defining a name and type.
  7. Select each field you want to add to the business object. Click Save to add the fields and close the dialog box.
    The dialog box displays a list of the fields provided by the selected resource that have not been added to your business object.
    Description of data-designer-objects-selectfield.png follows
    Description of the illustration data-designer-objects-selectfield.png
  8. Click Save to save the changes to the business object.

Adding More Business Objects From a Service

A business object can be created for each resource that is provided by a service, but in many cases applications do not need business objects for every resource. When you need to add more business objects for a service to those that you created initially, you use the Add Service wizard to define the business objects that you want to create. In the Services page of the Data Designer you can see the business objects that you already created for your services.

To add another business object from the service:

  1. Open Services in the Data Designer.
  2. Select the service that you want to modify.

    Description of data-designer-services-overview.png follows
    Description of the illustration data-designer-services-overview.png
    The right panel contains tabs that enable you to view details about the selected service, including the business objects and authentication details.
  3. Open the Business Objects tab for the service.
    The Business Objects tab displays a list of the business objects provided by the service that are available in your application.
    Description of data-designer-services-objects.png follows
    Description of the illustration data-designer-services-objects.png
  4. Click Add more business objects from this service to open the Business Objects step in the Add Service wizard.
  5. Select the resources you want to add as business objects. Click Finish.
    After you create the new business objects, use the Business Objects page to modify the fields.

Testing an External Service

Use the Services tab to check the connection to your services and view the data that is retrieved when calling the service.

To test a connected service:
  1. Open the Data Designer in the main menu.
  2. Open the Services tab.
    The left pane displays a list of your connected services.
  3. Select a service in the left pane.
  4. Open the Test Services tab.
    The Test Services tab displays a table with the fields of the service.
  5. Select a resource in the dropdown list. Click Test Resource.
A REST request is sent to the service and the main table is populated with the response. Below the main table are tabs for child and related objects. You can select a row in the main table to retrieve and populate the tables with data for the child and related objects.

Re-authorizing Security Credentials for a Service

The authentication settings for services need to be manually configured if you import an application.

The external REST services used in an application can be configured to use various authentication methods, including Basic, OAuth[User id] and OAuth[App id]. For security reasons, when an application is exported, the credentials and details on the authentication type are removed from the archive. When an application archive is imported, the security credentials for the services in the application might need to be manually re-configured. You will see a notification in your browser if you import an application that needs the security credentials re-authorized.

To configure the authentication credential for a service after importing an application:

  1. Open Services in the Data Designer.
  2. Select the service that you want to re-authorize.
    For each service in the application you should confirm that the credentials are configured correctly.
  3. Open the Authentication tab for the service.
  4. Specify the authentication credentials for the service. Click Save.

Setting REST API Versions of External Services

Use the Overview tab of in the Services page to set the versions of the REST APIs used when connecting to external REST services.

Connections to Sales Cloud services associated with your identity domain are automatically listed in your Services catalog. Sales Cloud provides REST APIs that expose the objects that you can use in your application. When you create a business object for a service in Visual Builder you design the calls to the REST service based on the description supplied by the API. By default, when you create the initial connection to a service the REST call is created against the most recent version if you do not explicitly specify a different version. To ensure that your REST calls continue to work after a REST API is updated, all calls will continue to use the API version that was used when the initial call was generated.

The API version specified in the Services page is used for all calls to the service. To change the REST API version to a different version you must explicitly change the version in the Services page.

  1. Open Services in the Data Designer.
  2. Select the service you want to modify and open the Overview tab.
  3. Modify the version of the REST API used by your application by selecting the version in the dropdown list.
    The default version displayed in the dropdown list is the API version that was used when the connection to the service was added to your application. Open the dropdown list to view other available versions of the API.
    Description of data-designer-services-overview2.png follows
    Description of the illustration data-designer-services-overview2.png
If you change the API version you might want to test the call to the service to confirm that the expected results are returned.

Adding a Shared Business Object

If a user has set the Application Shares Resources option for a published application, you can add one or more business objects from that application to your own application.

To add a shared business object:

  1. Open Business Objects in the Data Designer.
  2. Click New Business Object and select Select from Another Application.
    Description of data-designer-add-shared-bo1.png follows
    Description of the illustration data-designer-add-shared-bo1.png
  3. In the Add from Another Application text field, enter at least 3 characters to search for the business object you want to use.
    Description of data-designer-add-shared-bo2.png follows
    Description of the illustration data-designer-add-shared-bo2.png
    You may see a list of business objects, a list of applications, or both.
  4. Select the business object that you want to add to your application and click Add, or select an application and then select from its list of business objects.
    Description of data-designer-add-shared-bo3.png follows
    Description of the illustration data-designer-add-shared-bo3.png
    The selected business objects appear in the Data Designer along with a message that says what application they come from.
    Description of data-designer-add-shared-bo4.png follows
    Description of the illustration data-designer-add-shared-bo4.png

You can use the business objects, but you can’t make any changes to them.

If the user who created the application with the business objects creates a new version of the application with changed versions of the business objects, your business objects will continue to work correctly. There is no mechanism at present for upgrading to the newer version.

Creating Business Objects From a File

You can create new business objects by importing spreadsheet files and csv files using the Import New Business Objects wizard.

The files that you upload are analyzed to determine the business objects that can be created. You may upload comma-separated values text files (csv) or Excel spreadsheets (xls, xlsx). When using csv files to create business objects, one business object is created for each file, and the name of the business object is based on the file name. When using xls or xlsx files to create business objects, one business object is created for each worksheet in the file, and the name of the business object is based on the worksheet name. If the worksheet contains one or more tables, a business object is created for each table based on the table name and the worksheet name is ignored. The first row of csv files, worksheets and tables must be a header row, and the column headers are used to determine the names of the fields. The data in each column is parsed to help determine the data type for the field, but you should confirm the suggested data type is correct in the Fields step of the wizard.

To upload multiple files you need to create a zip archive containing the files you want to import.

You can open the Import New Business Objects wizard from the Data Designer in the following ways:

  • Open the Data Manager page and click Import Business Objects.

  • Open the Business Objects page and click Import. If your application has no business objects, you can click Import Business Objects on the empty Business Objects page.

To create business objects in the Import New Business Objects wizard:

  1. Open the Import New Business Objects wizard.
  2. In the Upload File step of the wizard, drag the file from your local system into the wizard, or click Select a file to import and locate the file on your local system.

    After the upload is complete, the wizard displays a list of the business objects and records found in the upload.


    Description of business-object-file-upload.png follows
    Description of the illustration business-object-file-upload.png

    Click Next.

  3. In the Business Objects step of the wizard, select the business objects that you want to create.

    The wizard displays a list of the business object that can be created and the files in your upload they are based on. You can select which business objects you want to create, and edit the names and object IDs of the new business objects. The checkbox in the Lookup column is selected when the business object is referenced as a lookup object by other tables. You can deselect the checkbox if you want to create a standard business object instead of a lookup object. After the business object is imported you cannot convert it to a lookup.


    Description of business-object-file-filenames.png follows
    Description of the illustration business-object-file-filenames.png

    Click Next.

  4. In the Fields step of the wizard, click the business object name to edit the names and types for each of the fields in the business object.

    The wizard displays tabs for each new business object. Each tab displays the fields that will be created in the business object, and a sample of the values stored in the field. For each business object you can edit the name, label and data type of the fields.


    Description of business-object-file-fields.png follows
    Description of the illustration business-object-file-fields.png

    You can click the Data Type icon for each field to open a dialog box where you can modify the type. If the data type is Lookup you can select the lookup business object. For Reference fields you can select the reference business object from an existing business object or from those that you are importing, and select the field in the referenced object to display.


    Description of business-object-file-lookups.png follows
    Description of the illustration business-object-file-lookups.png

    Click Finish.

The wizard displays a list of the new business objects that were successfully imported.


Description of business-object-file-apply.png follows
Description of the illustration business-object-file-apply.png

Working With Lookups

You can use lookups anywhere in your application where you want to select from a predefined list of values, for example, in a menu.

A lookup is a business object that stores a defined list of values (LOV) and is typically used in menus where only one value can be selected. To use a lookup in a business object you add a field that references either an existing lookup or one that you create. Once a lookup is created you can reference the lookup anywhere in your application where you want to use the same values, for example, a list of currencies. When you modify the values in the lookup, the change affects all the places where the lookup is referenced.

Lookups have the following characteristics:

  • A value can be modified or deactivated but it cannot be deleted

  • You can use a graphic icon to represent a value

You can only create new lookups in your application from the Page Designer by creating a new field in a business object. After you create the lookup you can add and modify values in the Data Designer.

To create a lookup:

  1. In the Page Designer, open the page where you want to add the field that will reference the lookup and click New Field.
    You can add the new field in the wizard when you are creating a business object or add it to an existing business object from the Data tab in the Property Inspector.
  2. In the New Field dialog box, type the Default Display Label for the field.
    The Field Name is generated automatically based on the display label.
  3. Select Lookup as the Field Data Type.
  4. Select Create New and type a name for the lookup.

    Description of lookup-create-dialog.png follows
    Description of the illustration lookup-create-dialog.png
    If you select Choose Existing you can select any of the existing lookups in your application.
  5. Click Define Lookup Values.
  6. For each value that you want to use, click Add Lookup Value and type the value.
  7. Optional: Click Add Icon button to add an icon that will represent the value.
    You can add icons to represent the value by selecting an image from the Image Gallery. Select Custom if you want to upload a new image to the gallery.
    Description of lookup-create-images.png follows
    Description of the illustration lookup-create-images.png
    Use the Property Inspector to configure the display options for the field. You can choose to display the value as text, image or both.
  8. Click Create.
When you create the field, the lookup business object is also created in your application. You can view and modify the lookup in the Business Objects page in the Data Designer.

Modifying Lookup Values

You can modify the lookups in your application to add values and change the values, display order and any icons used to represent values. Lookups can also be converted to standard business objects.

Note:

A lookup can be converted to a custom business object but a business object cannot be converted to a lookup. If you used icons to represent values in the lookup, the icons will no longer appear after the lookup is converted.

To modify a lookup:

  1. Open Business Objects in the Data Designer.
    The Business Objects page displays a list of business objects and lookups.
  2. Open the Overview tab for the lookup you want to modify.
    The Lookup Business Object checkbox is selected in the Overview tab when a business object is a lookup.
    Description of lookup-overviewtab.png follows
    Description of the illustration lookup-overviewtab.png
    To convert a lookup to a custom business object, deselect the Lookup Business Object checkbox and confirm the decision in the Convert Lookup dialog box.

    WARNING:

    Converting a lookup to a business object cannot be undone.
  3. Open the Data tab for the lookup.
    The Data tab displays the active and inactive values in the lookup, the icons representing the values and the order that they are displayed in your pages.
    Description of lookup-datatab.png follows
    Description of the illustration lookup-datatab.png
  4. Make your changes to the values.
    You can make the following changes to the list of values.
    • Add a new value

    • Change the order of values by dragging the menu icon for a value to a new location

    • Change the value by typing in the Values field

    • Click the Add Icon to add an icon representing the value

    • Toggle the Active option to deactivate a value. Deactivated values are not visible in your pages.