28 Working with Business Objects

Create a business object to filter the attributes and methods retrieved from a data source and render the retrieve data on your portal page using data visualization.

Permissions:

To perform the tasks in this chapter, you need one of the following portal-level permissions:

• Assets: Create, Edit, and Delete Assets or Create Assets and Edit Assets (standard permissions)

• Application Integration Visualization: Manage Application Integration Visualization (advanced permissions)

See About Roles and Permissions for a Portal.

Topics:

• About Business Objects

• Creating a Business Object

• Editing a Business Object

• Managing a Business Object

28.1 About Business Objects

Introduced in WebCenter Portal 12c (12.2.1) is the ability to retrieve data from a REST or SQL data source using a business object, simplifying the complexities of application integration. The retrieved data can be rendered on a portal page in a data visualization using a visualization template. For example, the data can be presented in one of the built-in visualization templates, or a developer can build a custom visualization template in JDeveloper.

The basic steps to accomplish this are:

1. Create data source. Create a REST or SQL data source from which to retrieve the data to present on the page (see Creating a REST Data Source and Creating a SQL Data Source).

2. (Optional) Create business object. If you need to filter the attributes and methods retrieved from the data source, create a business object (see Creating a Business Object). If you do not create a unique business object, one is automatically created when a data source is selected in the Define Data Visualization wizard, and all the attributes and methods for the data source are added to the business object. Manually-created business objects are listed on the portal Assets page and in the Define Data Visualization wizard, but automatically-created business objects are internal and not exposed anywhere.

3. Determine visualization template. Decide if you can use one of the built-in visualization templates (see About the Built-In Visualization Templates), or if you need to work with a developer to create a custom visualization template. When a custom visualization template is uploaded to a portal, it is shown on the Assets page for the portal; it can also be made available as a shared asset, available to all portals.

4. Configure data visualization. Add a data visualization component (Data Presenter Visualization) to a page, then configure the component to define the data visualization that you want to render on the page (see Configuring a Data Visualization).

The main function of a business object is to simplify the source of data to present that data on a portal page. When the data source is not complex, a business object is automatically created by WebCenter Portal when a data source is selected in the Define Data Visualization wizard. For an automatically-created business object, all the attributes and methods for the data source are added to the business object. In this case, the display name and description of each attribute and method are not available for configuration. Typically, advanced users create business objects manually as a portal asset, with a limited set of attributes that are relevant for building data visualizations. Business objects can be created only at the portal level (as a portal asset), not at the application level (as a shared asset).

A business object can expose multiple scalar attributes as well as collection attributes. For REST, it can support multiple methods such as GET, PUT, POST, and DELETE, based on support from the underlying REST data source. Each business object has a reference to the corresponding data service, which in turn has a reference to the underlying data control that provides the actual model to access the back-end data source.

28.2 Creating a Business Object

Before creating a business object, read About Business Objects.

You can use an automatically-created business object that includes all the attributes and methods from the data source, or manually create a business object that retrieves only the data that you specify. If a data source contains multiple levels of hierarchy and data at various levels, you can select only one level to create visualizations. For example, if a data source returns two iterators (repeating data, such as phone numbers), then even though a business object can contain both iterators, a data visualization will use only the first iterator. If you wish to use both iterators, then you must create two separate business objects. Manually-created business objects should be simple.

A business object is associated with a specific portal, and therefore can be created only at the portal level (as a portal asset), not at the application level (as a shared asset). When you create a business object to filter the attributes and methods retrieved from a data source, you can build it from scratch or create a copy of an existing business object and edit it. To build a new business object from scratch, follow the steps in the section. To copy an existing business object and edit the new copy, see:

• Copying an Asset

• Editing a Business Object

To create a business object:

1. Navigate to the Assets page for the portal in which you want to create the business object.

   For more information, see Accessing Portal Assets.

2. In the left pane, under Integration, click Business Objects.
3. In the toolbar, click Create (Figure 28-1) to open the Create New Business Object wizard, where you will define the data elements to include in the business object.

   Figure 28-1 Creating a Business Object

   
   Description of "Figure 28-1 Creating a Business Object"
4. In the Create New Business Object wizard (Figure 28-2), in the Name field, enter a name for the business object.
   The name is displayed in lists when selecting a business object.

   Note:

   A business object name cannot include the reserved words Business Object.

   Figure 28-2 Create New Business Object Wizard

   
5. (Optional) In the Description field, enter a description for the business object.

   The description is displayed below the name in the Assets page. Ensure that the description helps users determine if they want to use this particular business object.

6. On the Data Sources tab, define the data source to retrieve the data for the business object:

   Note:

   If you want to select an existing REST data source, but know that the underlying data has changed, you can exit the wizard and go to the Assets page of the portal to edit the data source (see Editing a REST Data Source), where you can select Refresh Schema to refresh the data source and business object with changes such as added, deleted, or renamed attributes. For more significant structural changes, you will need to re-create the data source, and any data visualizations where it is used.

   1. From the Type list, select the type of data source from which the business object will retrieve data (REST or SQL).
      The generated list shows all data sources that are portal assets of the selected type.
   2. From the generated list of data sources, select the required data source.
   3. From the Method list, select the method to be used to retrieve the data (for example, GET).
   4. In the generated list of methods, click the Expand icon on a method to view the attributes associated with the selected data source, then click the check boxes to select each attribute required by the business object (Figure 28-3). Click the UnSelect Children icon to deselect all check boxes.

      Figure 28-3 Create New Business Object: Attributes

      
7. On the Configuration tab:
   1. Click the Edit icon next to a method or attributes to modify a name or description for the Source retrieved from the data source.
   2. Click the Delete icon next to a method or attribute to remove it from the data to be retrieved by the business object.
8. On the Parameters tab, if parameters are present, click Edit to modify the name and/or value of a parameter.

   Parameters listed are those retrieved from the data source. For example, if you create a SQL data source using a query with bind variables, then all bind variables are exposed as parameters. Similarly, for a REST data source, parameters are specified in the Resource URL (for example, http://example.com/stocks?symbol=ORCL, where symbol is a parameter). Parameter names in a business object are formed using the syntax paramName_method. For example, using the REST data source example above, the default business object parameter name will be symbol_GET. You can change the name of the parameter as desired.

9. On the Preview tab, click Test to preview the data retrieved from the data source based on your selections.
10. Click Save.
    The newly created business object is listed on the Assets page (Figure 28-4). By default, the check box in the Available column is selected, indicating that the business object is published and available to users to bind to a data visualization (see Configuring a Data Visualization).

    Figure 28-4 New Business Object on Assets Page

    

28.3 Editing a Business Object

You can edit a business object to change its configuration settings.

To edit a business object:

1. Navigate to the Assets page for the portal that owns the business object. For more information, see Accessing Portal Assets.
2. In the left pane, under Integration, click Business Objects.
3. In the Actions column for the business object that you want to edit, click the Edit quick link (Figure 28-5) to open the Edit Business Object wizard.

   Figure 28-5 Edit Business Object Asset

   
4. In the Edit Business Object wizard (Figure 28-6), make required modifications to the Name, Description, and settings on the Data Sources, Configuration, and Parameters tabs. For more information about the settings, see Creating a Business Object.

   Figure 28-6 Edit Business Object Wizard

   
5. Click Save to save your changes to the business object and close the wizard.

28.4 Managing a Business Object

The following options are available on the Assets page to enable you to manage business objects.

See Also:

Accessing Portal Assets

,

• Create—You can create a new business object in the Create Business Object wizard.

  For more information, see Creating a Business Object.

• Delete—You can delete a business object when it is no longer required.

  For more information, see Deleting an Asset.

• Actions

  • Copy—You can create a copy of an existing business object, to use as the basis for a new business object.

    For more information, see Copying an Asset.

  • Edit Properties—Each business object has certain properties associated with it that control how it is displayed in the portal. You can edit these properties through the Edit Properties dialog.

    For more information, see Setting Properties on an Asset.

  • Show Properties—Each business object has an associated Show Properties dialog that summarizes useful information about it.

    For more information, see Viewing Information About an Asset.

• Available—You can control whether or not a business object is available for use in a portal by selecting or deselecting this check box.

  For more information, see Showing and Hiding Assets.

• Edit—You can edit an existing business object in the Edit Business Object wizard.

  For more information, see Editing a Business Object.