4 Customizing and Extending Oracle ADF Application Artifacts

This chapter describes how to use Oracle JDeveloper to customize and extend application artifacts defined by Oracle Application Development Framework (Oracle ADF) in Oracle Fusion applications.

This chapter includes the following sections:

4.1 About Customizing Oracle ADF Application Artifacts

With the customization features provided by Oracle Metadata Services (MDS), developers can customize Oracle Fusion Applications using JDeveloper, making modifications to suit the needs of a particular group, such as a specific country or site.

Using JDeveloper, you can implement customizations on existing artifacts that are stored in a metadata repository and retrieved at runtime to reveal the customized application. You can also extend you application with new custom artifacts that are packaged into a JAR file, and integrated using customizations on the existing application.

Note that many kinds of customizations can be performed in the runtime environment using Oracle Fusion CRM Application Composer, which allows you to customize existing objects and extend an application with new objects for the following CRM applications:

Sales
Common

However some kinds of customization (including all customizations to applications other than those listed above) require a lower level approach, for which you will need to use JDeveloper.

4.1.1 Before You Start Customizing Oracle ADF Application Artifacts

Before you customize application artifacts (such as entity objects, view objects, application modules, and pages) using JDeveloper, you should be familiar with the Oracle Fusion application architecture that enables customization, as described in Customizing and Extending . You should also understand the typical workflows for working with customizations, as described in Understanding the Customization Development Life Cycle.

Before you make any changes to the data model such as adding entity objects or attributes, first check to see if there is an existing flexfield that meets your needs.

For information about implementing flexfields, do the following:

Access the Oracle Fusion Applications Technology library.
See the Implementing Common Features guides for your product family. Search for flexfields.

WARNING:

Do not use JDeveloper to customize flexfields. If you require flexfield changes that you cannot accomplish using the Manage Flexfields tasks or the Manage Value Sets tasks, contact My Oracle Support at https://support.oracle.com or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.

In addition, you will need to perform the following tasks before you can begin customizing your application:

Set up a test environment.

All application artifact customizations should be deployed to a test environment. For more information, see Understanding the Customization Development Life Cycle.
Determine which artifacts you want to customize.

Before you can implement customizations using JDeveloper, you must first determine which objects you want to customize, so that you can create a customization application workspace that imports the necessary parts of the application. For more information, see Customizing Artifacts with .
Create an application workspace.

Before you can implement customizations using JDeveloper, you must create a customization application workspace that imports the necessary parts of the application you want to customize. For more information, see Creating the Customization Application Workspace.
Start JDeveloper in the appropriate role.

If you are implementing customizations on existing application artifacts, you must select the Oracle Fusion Applications Administrator Customization role when you start JDeveloper.

If you are creating new custom application artifacts (such as entity objects, view objects, and pages), you must select the Oracle Fusion Applications Developer role when you start JDeveloper.
Select a layer value.

When customizing application artifacts in JDeveloper, you must first select the layer and layer value to work in. You use the Customization Context window to make this selection. When customizing business components, such as entity objects and view objects, you must use the global layer. For more information about customization layers, see About Customization Layers.

4.1.2 About Customizing at the Role Level

The layers and layer values that are available depend on which application you are customizing, and the Role layer is not available in all Oracle Fusion applications. CRM applications have a Role layer that you can select in the Customization Context window, while other applications do not.

To implement role-level customizations in an application that does not have a Role layer, you can use an expression in the rendered property of a component to conditionally render the component based on specified security level associated with a role. For example, you might want to display a button or a column in a table only to users that have the role of manager.

4.1.2.1 Conditionally Rendering a Button Based on a Role

Start JDeveloper in the Oracle Fusion Applications Administrator Customization role.
Select the layer in which to customize. (Remember that if you want to customize an ADF Business Components object, such as an entity object or view object, then you must use the global layer.)
Open the page that contains the button, and then in the Properties window, click the Property Menu icon beside the Rendered field.
Select Expression Builder. In the Expression Builder dialog, enter an EL expression like the one in Example 4-1.

The permission in this example is a string containing a semicolon-separated concatenation of permissionClass=class;target=artifact_name;action=action. This expression evaluates to False for users that have not been granted the permission, and the button is not rendered in the page. For more information, see the "Enabling ADF Security in a Fusion Web Application" chapter in the Developing Fusion Web Applications with Oracle Application Development Framework.

Example 4-1 EL Expression to Verify Security

#{securityContext.userGrantedPermission['permission']}

4.2 About Editing Existing Business Components

When customizing an application in JDeveloper, be aware that the layer in which you choose to implement customizations has an impact on what kinds of customizations you can perform. If you want to customize an ADF Business Components object, such as an entity object or view object, then you must use the global layer.

Before you start customizing business objects, determine which business objects you want to customize and create a customization application workspace. For more information, see Before You Start Customizing Application Artifacts.

Then when customizing ADF artifacts, you need to start JDeveloper in the Oracle Fusion Applications Administrator Customization role, and then select the global layer.

4.2.1 About Editing Attributes

You can customize the properties of an attribute from an entity object or view object using JDeveloper. When you open an entity object or view object in the overview editor, you click the Attributes navigation tab to see the attributes of the object. When you select an attribute, its properties are displayed in the Property Inspector.

It is not necessary to modify the page after customizing the properties of an existing attribute. Customizations to existing attributes are automatically reflected on the pages that show them.

However, if you modify an attribute so that it requires a different UI component, then you must also update the page. For example, if you add a list of values (LOV) to an attribute, then you must edit the page to hide the existing UI component that displays the attribute, and add a new UI component that can display the LOV.

Note that some attribute properties defined in the entity object can be overridden in the view object. For example, you can define the label text for a field in an entity object and subsequently give it a different label in the consuming view object. Then pages that use the view object display the label from the view object.

For more information about attributes in entity objects, see the "Creating a Business Domain Layer Using Entity Objects" chapter in the Developing Fusion Web Applications with Oracle Application Development Framework.

4.2.2 About Adding Attributes

You can add custom attributes to an entity object or view object using JDeveloper. To do this, you must start JDeveloper in the Oracle Fusion Applications Administrator Customization role, and then select the global layer. When you open an entity object or view object in the overview editor, you click the Attributes navigation tab to see the attributes of the object. To add a custom attribute, click the Add icon.

If you want your custom attribute to be stored in the database, then you must first create the column that will be use to store it.

If you want your custom attributes to be displayed in the application, then you must also customize the pages to display them. For more information, see Editing Pages.

4.2.3 About Editing Entity Objects

In JDeveloper, you edit entity objects using the overview editor. In the Application Navigator, right-click an entity object, and choose Open. Then click the navigation tabs to view and edit the various features of the entity object.

For more information about entity objects, see the "Creating a Business Domain Layer Using Entity Objects" chapter in the Developing Fusion Web Applications with Oracle Application Development Framework.

For more information about using entity objects in Oracle Fusion applications, see the "Getting Started with Business Services" chapter in the Developer's Guide.

4.2.4 About Editing View Objects

In JDeveloper, you edit view objects using the overview editor. In the Application Navigator, right-click a view object, and choose Open. Then click the navigation tabs to view and edit the various features of the view object.

For more information about view objects, see the "Defining SQL Queries Using View Objects" chapter in the Developing Fusion Web Applications with Oracle Application Development Framework.

For more information about using view objects in Oracle Fusion applications, see the "Getting Started with Business Services" chapter in the Developer's Guide.

4.2.5 About Editing Validation

In JDeveloper, you edit declarative validation rules for entity objects and view objects using the overview editor. In the Application Navigator, right-click an entity object or view object, and choose Open. Then click the Business Rules navigation tab to view and edit the validation rules.

When implementing customizations on validation rules, you can add rules, modify the error message, and make rules more restrictive. But avoid removing rules or making rules less restrictive, because this can cause unpredictable results. Also, you can edit only declarative validation rules; programmatic validation rules cannot be customized.

For more information, see the "Defining Validation and Business Rules Declaratively" chapter in the Developing Fusion Web Applications with Oracle Application Development Framework.

4.2.6 Customizing Business Logic Using Groovy Triggers

In JDeveloper, you can implement Groovy script to respond to predefined trigger points (such as, Before Delete in Database or After Create) for an entity object. These trigger points are available on the Business Rules page of the overview editor for entity objects.

In the Application Navigator, right-click an entity object, and choose Open.
Click the Business Rules navigation tab to view the existing validation rules.
Click the Add icon and choose Trigger to display the Add Trigger dialog, which allows you to select a trigger point and enter a Groovy expression that will be executed in response to it.

For more information, see the "Customizing Applications with MDS" chapter in the Developing Fusion Web Applications with Oracle Application Development Framework.

4.2.7 About Editing Application Modules

In JDeveloper, you edit application modules using the overview editor. In the Application Navigator, right-click an application module, and choose Open.

In JDeveloper, you can make the following kinds of customizations on an application module:

Add new custom properties. This is done on the General page of the overview editor.
Add new view object and application module instances. This is done on the Data Model page of the overview editor.
Add newly created subtype view objects. This is done on the Data Model page of the overview editor.
Add new application module configurations. This is done on the Configurations page of the overview editor.

It is important to note that you cannot modify the web service interface for a service-enabled application module. You can, for example, add an attribute in a view object that is included in a service-enabled application module, but that attribute cannot be added to the web service interface.

For more information about working with application modules, see the "Implementing Business Services with Application Modules" chapter in the Developing Fusion Web Applications with Oracle Application Development Framework.

4.2.8 About Adding Customizations to Existing Reports

After you have implemented customizations on your application, you can use Oracle Business Intelligence Publisher to include these customizations in your reports. For more information, see the "Customizing Reports and Analytics" chapter in the .

4.3 About Editing Task Flows

You can use JDeveloper to implement customizations on the task flows that are used in your application. A task flow is a set of ADF Controller activities, control flow rules, and managed beans that interact to allow a user to complete a task. Although conceptually similar, a task flow is not the same as a human task, a task in the worklist, or a process flow.

A bounded task flow can be rendered in a JSF page or page fragment (.jsff) by using an ADF region. This is typically done to allow reuse of the task flow, as necessary, throughout the application. If you modify a bounded task flow, the changes apply to any ADF region that uses the task flow. For more information, see the "Using Task Flows as Regions" chapter in the Developing Fusion Web Applications with Oracle Application Development Framework.

Before you start editing task flows, you will need to determine which task flows you want to customize, and create a customization application workspace. For more information, see Before You Start Customizing Application Artifacts.

When editing a task flow in JDeveloper, you must start JDeveloper in the Oracle Fusion Applications Administrator Customization role.

In JDeveloper, you use the task flow diagram editor to implement customizations on existing task flows. In the Application Navigator, right-click the task flow you want to customize, and choose Open. The page is displayed in the diagram editor, where you can make changes to the existing activities and control flow cases, or create new custom ones. For more information, see the "Getting Started with ADF Task Flows" chapter in the Developing Fusion Web Applications with Oracle Application Development Framework.

4.4 Editing Pages

You can use JDeveloper to implement customizations on the pages that are used in your application. When editing a page in JDeveloper, you must start JDeveloper in the Oracle Fusion Applications Administrator Customization role.

Before you start editing pages, you will need to determine which pages you want to customize, and create a customization application workspace. For more information, see Before You Start Customizing Application Artifacts.

In JDeveloper, you use the visual editor to implement customizations on existing pages.

In the Application Navigator, right-click the page you want to customize, and choose Open.
Click the Design tab to display the page in the visual editor.
Edit the page as you typically would using this editor.

For more information about editing pages in JDeveloper, see the Developing Web User Interfaces with Oracle ADF Faces.

4.5 About Creating Custom Business Components

You can use JDeveloper to extend your application by creating custom business components. When creating custom business components in JDeveloper, you must start JDeveloper in the Oracle Fusion Applications Developer role. This role is used for creating new custom objects that you want to add to the application. You can use the same application workspace that you created for customization. Then after you have created the custom business components, you switch to the Oracle Fusion Applications Administrator Customization role, to make changes to existing artifacts to integrate the new custom artifacts into the application.

Before you start creating business objects, determine which business objects you want to create, and create a customization application workspace. For more information, see Before You Start Customizing Application Artifacts.

4.5.1 Creating Custom Entity Objects

An entity object represents a row in a database table, and encapsulates the business logic and database storage details of your business entities.

In JDeveloper, you can create entity objects using the Create Entity Object wizard, which you can access from the New Gallery.

In the Application Navigator, right-click the project you want to add the entity object to, and choose New.
In the New Gallery, do the following:
1. Expand Business Tier.
2. Click ADF Business Components, and then choose Entity Object.
3. click OK.
4. Follow the prompts in the wizard to create an entity object.

For more information about creating entity objects, see the "Creating a Business Domain Layer Using Entity Objects" chapter in the Developing Fusion Web Applications with Oracle Application Development Framework.

For more information about using entity objects and view objects in Oracle Fusion applications, see the "Getting Started with Business Services" chapter in the Developer's Guide.

4.5.2 Creating Custom View Objects

A view object represents a SQL query and also collaborates with entity objects to consistently validate and save the changes when end users modify data in the UI.

In JDeveloper, you can create view objects using the Create View Object wizard, which you can access from the New Gallery.

In the Application Navigator, right-click the project you want to add the view object to, and choose New.
In the New Gallery, do the following:
1. Expand Business Tier.
2. Click ADF Business Components, and then choose View Object.
3. click OK.
4. Follow the prompts in the wizard to create a view object.

For more information about creating view objects, see the "Defining SQL Queries Using View Objects" chapter in the Developing Fusion Web Applications with Oracle Application Development Framework.

For more information about using entity objects and view objects in Oracle Fusion applications, see the "Getting Started with Business Services" chapter in the Developer's Guide.

4.5.3 Creating Custom Application Modules

An application module encapsulates an active data model and the business functions for a logical unit of work related to an end-user task.

In JDeveloper, you can create application modules using the Create Application Module wizard, which you can access from the New Gallery.

In the Application Navigator, right-click the project you want to add the application module to, and choose New.
In the New Gallery, do the following:
1. Expand Business Tier.
2. Click ADF Business Components, and then choose Application Module.
3. click OK.
4. Follow the prompts in the wizard to create an application module.

For more information about creating application modules, see the "Implementing Business Services with Application Modules" chapter in the Developing Fusion Web Applications with Oracle Application Development Framework.

For more information about using application modules in Oracle Fusion applications, see the "Getting Started with Business Services" chapter in the Developer's Guide.

4.5.4 Creating a Web Service Interface for a Custom Application Module

In JDeveloper, you can edit a custom application module to create a web service interface that exposes the top-level view objects and defines the available service operations it supports.

Open the application module in the overview editor, and click the Service Interface navigation tab.
Click the Enable support for Service Interface icon.
Use the Create Service Interface wizard to configure the desired options.

Note:

The new web service cannot be deployed to the Oracle Fusion application. You can deploy it only to a new application.

For more information about creating a web service interface for an application module, see the "Integrating Service-Enabled Application Modules" chapter in the Developing Fusion Web Applications with Oracle Application Development Framework.

For more information about using application modules in Oracle Fusion applications, see the "Getting Started with Business Services" chapter in the Developer's Guide.

4.5.5 Adding Validation

In JDeveloper, you can create declarative validation rules for entity objects and view objects to help ensure the integrity of the data.

Open the entity object or view object in the overview editor.
Click the Business Rules navigation tab.
Select the attribute you want to provide validation for, and click the Create new validator icon.
Configure the rule using the Add Validation Rule dialog.

For more information, see the "Defining Validation and Business Rules Declaratively" chapter in the Developing Fusion Web Applications with Oracle Application Development Framework.

4.5.6 About Enforcing Data Security for a Custom Business Object

You can use JDeveloper to enforce row and attribute security for custom ADF Business Components objects. This is done using data security policies to secure data from business objects based on the grants made to roles.

When you need to expose data records in an extended application, you can use JDeveloper to create entity objects based on secured database resources, and then opt into data security policies by enabling row-level privilege checking for specific operations on the entity objects. For more information, see About Enforcing Data Security in the Data Model Project.

4.5.7 About Adding a Business Object to an Existing Report

After you have extended your application with custom business objects, you can use Oracle Business Intelligence Publisher to include these extensions in your reports. For more information, see the "Customizing Reports and Analytics" chapter in the .

4.6 About Creating Custom Task Flows

You can use JDeveloper to create custom task flows that you can include in your application. A task flow is a set of ADF Controller activities, control flow rules, and managed beans that interact to allow a user to complete a task. Although conceptually similar, a task flow is not the same as a human task, a task in the worklist, or a process flow.

Before you start creating custom task flows, determine which task flows you want to create, and create a customization application workspace. For more information, see Before You Start Customizing Application Artifacts.

When extending your application with custom task flows in JDeveloper, you must start JDeveloper in the Oracle Fusion Applications Developer role.

4.6.1 Creating a Custom Task Flow

You can create a custom task flow in JDeveloper using the New Gallery, and then define its activities using the task flow diagram editor.

In the Application Navigator, right-click the project you want to add the task flow to, and choose New.
In the New Gallery, expand Web Tier, and click JSF/Facelets.
Select ADF Task Flow, and click OK.
In the Create Task Flow dialog, specify the details about the type of task flow you want to create.
Click OK

The task flow is created and displayed in the diagram editor.

For information about creating and designing task flows, see the "Getting Started with ADF Task Flows" chapter in the Developing Fusion Web Applications with Oracle Application Development Framework.

4.7 About Creating Custom Pages

You can use JDeveloper to create custom pages that you can include in your application. When creating custom pages in JDeveloper, you must start JDeveloper in the Oracle Fusion Applications Developer role.

When creating the page (or dropping a view activity onto a task flow), you can create the page either as a JSF JSP or as a JSF JSP fragment. JSF fragments provide a simple way to create reusable page content in a project, and are what you use when you want to use task flows as regions on a page. When you modify a JSF page fragment, the JSF pages that consume the page fragment are automatically updated.

After extending your application with custom pages, you will need to make sure that security for the new pages is implemented appropriately and that the new pages are deployed so that they are accessible from the application. For more information about updating security, see Customizing Security for Application Artifacts . For more information about deployment, see About Deploying Customizations and Extensions.

For more information about creating pages in JDeveloper, see the following resources:

The Developing Web User Interfaces with Oracle ADF Faces
"Getting Started with Your Web Interface" in the Developing Fusion Web Applications with Oracle Application Development Framework
"Implementing UIs in JDeveloper with Application Tables, Trees and Tree Tables" in the Developer's Guide
"Implementing Applications Panels, Master-Detail, Hover, and Dialog Details" in the Developer's Guide
"Creating Customizable Applications" in the Developer's Guide

Before you start creating custom pages, determine which pages you want to create, and create a customization application workspace. For more information, see Before You Start Customizing Application Artifacts.

When creating custom pages in JDeveloper, you must start JDeveloper in the Oracle Fusion Applications Developer role.

Task: Add a Custom Page to a Task Flow

If you created the page by double-clicking a view activity in a task flow, then it is already added to the task flow. If you created it using the New Gallery, then you can add it to a task flow by dragging the page from the Application Navigator and dropping it in the task flow diagram editor. Then you can connect the page using a control flow. For more information, see the "Getting Started with ADF Task Flows" chapter in the Developing Fusion Web Applications with Oracle Application Development Framework.

Task: Enable Runtime Customization for a Custom Page

To enable a custom page to be customized at runtime, you must make sure that the page and the project that contains it are set to allow runtime customizations. For information on how to do this, see the "How to Authorize the Runtime Customization of Pages and Task Flows" section in the Developer's Guide.

4.7.1 Creating a Custom Page

In JDeveloper, you can create pages either by double-clicking a view activity in a task flow or by using the New Gallery.

In the Application Navigator, right-click the project you want to add the task flow to, and choose New.
In the New Gallery, expand Web Tier, and click JSF/Facelets.
Select either Page orADF Page Fragment, and click OK.

4.8 About Customizing and Extending the Oracle Fusion Applications Schemas

Using the database tools of your choice, you can customize and extend the Oracle Fusion Applications schemas to suit the needs of your organization. However, you should first consider using Application Composer or flexfields to satisfy your additional data storage requirements. For more information about using Application Composer, see Oracle Cloud Extending Sales.

If you need to extend the preconfigured Oracle Fusion Applications schemas to address additional data storage needs, create a custom schema. In your custom schema, you can create tables, columns, and all the necessary additional schema objects. This approach allows you to contain and maintain all of your custom data storage objects separately from the preconfigured Oracle Fusion Applications schemas.

If necessary, you can extend the preconfigured schemas within certain constraints. With the exception of customizing a preconfigured table to include new custom objects, such as columns, you must not make any customizations to preconfigured schema objects. Instead, you can extend the schema by adding new custom objects that you can configure as needed.

When making amendments to the schema, such as adding tables or columns, add a prefix to the name of the table or column that is a unique identifier (for example, XX_) to prevent collisions with existing objects.

Any code that accesses the new custom schema objects should use fully qualified table names (for example, SCHEMA_NAME.TABLE_NAME). If your code does not use fully qualified table names, you will need to create synonyms for the custom tables. The synonym must be created in the FUSION schema, and associated privileges must be granted in the FUSION_RUNTIME schema. At runtime, Oracle Fusion applications connect to the FUSION_RUNTIME schema, so privileges must be granted there. However, because the schema context is set to FUSION, the synonym must be created there. This convention applies in all cases, whether you create custom schema objects in a custom schema or a preconfigured schema.

Note that if you are writing a custom application that is a peer application to an existing Oracle Fusion Applications module, you must define a custom schema that contains all the database objects for your custom application. Additionally, to integrate your custom application using a public Oracle Fusion Applications PL/SQL API, you must:

Grant EXECUTE privilege to the custom schema on the Oracle Fusion Applications PL/SQL package.

Public APIs in the Oracle Fusion Applications PL/SQL package are owned by the FUSION schema and are defined with the AUTHID DEFINER clause. This way when the custom schema invokes a PL/SQL API, the application will run with the set of privileges of the FUSION user, so there is no need to grant additional object privileges to the custom schema in order for the program to execute successfully.
Refer to the package and its procedures and functions using a fully qualified name, for example: FUSION.<package_name>.<procedure_name>

If your custom application will interact with objects in the FUSION schema (for example interface tables), then you must also:

Grant the necessary privileges on Oracle Fusion Applications objects to the custom schema (for example, INSERT privileges on interface tables) as necessary.
Refer to objects in the FUSION schema with fully qualified names, for example: FUSION.<table name>

For information about creating database objects, see the Designing Databases topics in the JDeveloper online help.

For information about implementing your specific product family, do the following:

Access the Oracle Fusion Applications Technology library.
See the Implementing Common Features guides for your product family. Search for flexfields.

4.8.1 What You Can Do with Schema Modifications

Using the SQL Worksheet in JDeveloper or the database tools of your choice, you can issue commands to the database to customize and extend it. When making changes to the database, you can do the following:

Add a custom schema
Add or modify tables
Add columns to preconfigured or custom tables
Add indexes to custom columns
Add sequences
Add PL/SQL packages, procedures, functions and abstract data types

4.8.2 What You Cannot Do with Schema Modifications

When making changes to the database, you cannot do any of the following:

Modify preconfigured columns or sequences.
Modify preconfigured PL/SQL packages, procedures, functions and abstract data types (unless explicitly directed to do so by product documentation).
Delete preconfigured schema objects.
Add indexes to preconfigured columns (unless explicitly directed to do so by product documentation).

4.8.3 About Extending the Schemas Using a Custom Schema

Using the SQL Worksheet in JDeveloper, you can issue commands to the database to customize and extend it. In a custom schema, you can add tables, columns, indexes, and other schema objects to support the customizations and extensions you want to implement in the application (such as, adding an attribute to an entity object).

Before you attempt to extend the schema, you should be familiar with the guidelines described in About Customizing and Extending the Schemas.

To access the SQL Worksheet, right-click the database connection (under the Connections node in the Application Resources panel of the Application Navigator), and choose Database Navigator from the context menu. This will open the selected database connection in the Database Navigator and display the SQL Worksheet.

4.8.3.1 About Creating a Custom Schema

When creating a custom schema, add a prefix to the name of the schema that is a unique identifier (for example, XX_) to prevent collisions with existing schemas. You must grant the privileges to the custom schema that are necessary for it to function properly and for any supporting code to compile (for example, objects referenced in PL/SQL code).

4.8.3.2 About Creating Custom Database Tables, Columns, Indexes, and Sequences

Within a custom schema, you can create custom database tables, columns, indexes, and sequences to address your additional data storage needs. When adding custom objects, add a prefix to the name of the object that is a unique identifier (for example, XX_) to prevent collisions with existing objects. New custom indexes and sequences should adhere to this convention as well.

After creating a custom table, you will need to grant the necessary object privileges to the FUSION_RUNTIME schema, which Oracle Fusion Applications uses at runtime. You can grant privileges directly to the schema, or through a custom database role, but do not use the preconfigured FUSION_APPS_READ_AND_WRITE database role.

4.8.3.3 About Creating Custom PL/SQL Packages, Procedures, Functions, and Abstract Data Types

When adding PL/SQL objects and abstract data types to a custom schema, add a prefix to the name of the object or data type that is a unique identifier (for example, XX_) to prevent collisions with existing objects.

Your PL/SQL code should contain the AUTHID INVOKER clause so that the code is executed within the context of the privilege set of the FUSION_RUNTIME user. Additionally, the FUSION_RUNTIME user must be granted the EXECUTE privilege on the PL/SQL object or type, either directly or through a database role.

If you need to create synonyms to support your PL/SQL code, then create your synonyms in the FUSION schema, as described in About Customizing and Extending the Schemas.

4.8.4 About Extending a Preconfigured Schema

Using the SQL Worksheet in JDeveloper, you can issue commands to the database to customize and extend it. When making changes to the schema, you can add tables or columns to support the customizations and extensions you want to implement in the application (such as, adding an attribute to an entity object). However, do not remove tables or columns, because this can have adverse affects in other parts of the application.

With the exception of customizing a preconfigured table to include new custom objects, such as columns, you must not make any customizations to preconfigured schema objects.

Before you implement extensions to a preconfigured schema, consider creating your extensions in a custom schema. This approach provides greater flexibility and modularity.

Also, you should be familiar with the guidelines described in About Customizing and Extending the Schemas.

4.8.4.1 About Editing Database Tables

With the exception of customizing a preconfigured table to include new custom objects, such as columns, you must not make any customizations to preconfigured schema objects.

When adding columns to a preconfigured table, add a prefix to the name of the column that is a unique identifier (for example, XX_) to prevent collisions with existing columns.

4.8.4.2 About Creating Custom Database Tables, Columns, Indexes, and Sequences

You can create custom database tables and columns to address your additional data storage needs. When adding custom tables and columns, add a prefix to the name of the table and columns that is a unique identifier (for example, XX_) to prevent collisions with existing tables and columns.

You can create new custom indexes on custom columns, but do not attempt to create an index on a preconfigured column, unless explicitly directed to do so by product documentation.

4.8.4.3 About Creating Custom PL/SQL Packages, Procedures, Functions, and Abstract Data Types

When adding PL/SQL objects and abstract data types, add a prefix to the name of the object or data type that is a unique identifier (for example, XX_) to prevent collisions with existing objects.

If you need to create synonyms to support your PL/SQL code, then create your synonyms in the FUSION schema, as described in About Customizing and Extending the Schemas.

4.9 About Customizing or Creating a Custom Search Object

In JDeveloper, you can customize and create saved searches and search forms for your application. To customize a search form or saved search in JDeveloper, you will need to set up an application workspace as described in Creating the Customization Application Workspace. Then, locate and open the object you want to customize. To create a new search form, you open or create the page that will display the form and select a data collection from the Data Controls panel. For more information, see the "Creating ADF Databound Search Forms" chapter in the Developing Fusion Web Applications with Oracle Application Development Framework.

[[ per RobinW: You will use ECSF for both adding new objects to a search and having changes to an object reflected in the search. But, per KenM: ECSF and saved searches are different artifacts. ]]

4.10 About Editing the UI Shell Template

To edit the UI Shell template in JDeveloper, you will need to set up an application workspace as described in Creating the Customization Application Workspace. Then, in the Oracle Fusion Applications Administrator Customization role, expand the contents of the Applications Core (ViewController) library and drill down to the file oracle/apps/fnd/applcore/templates/UIShell.jspx. This is the UI Shell template, which you can customize as necessary.

Alternatively, you can access the UI Shell template from any page in the library. Open the page in JDeveloper, right-click on the view ID of the pageTemplate tag (/oracle/apps/fnd/applcore/templates/UIShell.jspx), and then choose Go to Declaration to open the UI Shell template.

You can also use Page Composer to edit the UI Shell template, as described in the "Customizing Pages" chapter in the .

In addition, you can customize the Oracle Fusion Applications skin using ADF Skin Editor as described in Customizing the Skin .

4.11 About Customizing Menus

Using JDeveloper you can customize the menus in your Oracle Fusion applications. Customizing the tasklist menu follows the same pattern as editing most artifacts (such as, pages or business components) from the EAR connection. However, customizing the home page, preferences and navigator menus is slightly different. For these menus, you will need to export the menu's XML file from the MDS repository and copy them into your customization application workspace before you can implement customizations.

Note:

You can also customize the navigator menu at runtime from the Setup and Maintenance work area.

For information about implementing your specific product family, do the following:

Access the Oracle Fusion Applications Technology library.
See the Implementing Common Features guides for your product family. Search for "Manage Menu Customizations".

To export the menu files for an application, you use the exportMetadata Oracle WebLogic Scripting Tool (WLST) command. For more information, see the "Application Metadata Management Commands" section of WLST Command Reference for WebLogic Server. This command saves the files in a JAR file that you can import into your application workspace. For procedures, see the "Viewing ADF Library Runtime Customizations from Exported JARs" section of the Developing Fusion Web Applications with Oracle Application Development Framework.

Tip:

You can also use Oracle Enterprise Manager Fusion Applications Control to import and export metadata files. For more information, see the "Transferring Metadata Using Fusion Middleware Control" section of the Administering Oracle Fusion Middleware. The referenced procedure describes using Fusion Middleware Control, but also applies to Fusion Applications Control.

When exporting the menu XML files from the MDS repository, you can find them in the oracle/apps/menu directory in the repository. The following are their file names:

Home page menu: homepage_menu.xml
Preferences menu: pref_menu.xml
Navigator menu: root_menu.xml

Then you copy the files to the same directory (under project source path) in your local customization application workspace (for example, CUSTOMIZATION_APP_PATH/PROJECT_NAME/src/oracle/apps/menu). After you have copied them into your local customization application workspace, you can customize the menus as necessary.

After you have implemented customizations on a menu, you will need to update the MAR profile to make sure they are included during deployment. In the MAR profile, under User Metadata > Directories, select the customizations you implemented that correspond to the menu files. For more information about deploying customizations, see About Deploying Customizations and Extensions.

For more information about menus in Oracle Fusion Applications, see the "Working with the Global Menu Model" section in the Developer's Guide.

4.12 About Customizing or Adding Static Instructions, In-Field Notes, and Terminology Definitions

Oracle Fusion Applications embedded help (aside from bubble help) uses two types of ADF Faces help: instruction and definition. Instruction-type help displays static text, either in a specified area on a component (like static instruction help), or in a note window, as in-field notes do. Definition-type help displays a help icon, and is what terminology definition embedded help uses. When the user mouses over the help icon, the help text is displayed in a message box. UI components display the instruction and definition help text using the helpTopicId attribute. For more information about the ADF Faces help framework, see the "Displaying Help for Components” section in the “Displaying Tips, Messages, and Help” chapter of the Developing Web User Interfaces with Oracle ADF Faces.

It is important that for the type of help you want to add or customize, you understand which component actually displays the help, and which type of ADF Faces help is being used. Table 4-1 shows the different types of Oracle Fusion Applications embedded help, the corresponding ADF Faces help, and the components that display that type of help.

Table 4-1 Oracle Fusion Applications Help and Corresponding ADF Faces Help and UI Components

Oracle Fusion Applications Help Type	ADF Faces Help Type	Component
Static instruction	instruction	Page header Subheader Sub-subheader
In-field note	instruction	Multiselect check box group Single-select choice list Multiselect choice list Single-select list box Multiselect list box Text box Single-select radio groups Items in true/false radio groups Items in true/false check box groups Color picker Date/time picker Flexfield LOV Spin box Slider File upload Shuttle Rich Text Editor
Terminology definition	definition	Check box prompt Check box group prompt Single-select choice list Multiselect choice list Single-select list box Multiselect list box Text box Radio group prompt Color picker Date/time picker Flexfield LOV Column headers Spin box Slider File upload Shuttle Rich Text Editor

You perform the following tasks in JDeveloper in the Oracle Fusion Applications Administrator Customization role.

Note:

You cannot directly customize the existing help text strings. If you want to change text that currently appears, you must create a new text string and associate the component with that new text.

4.12.1 About Adding Help Strings to a Resource Bundle

Add custom help text strings to an existing custom resource bundle or create a new resource bundle to hold your customized help text (Oracle Fusion applications use XLIFF files for resource bundles). If you create a new resource file, you must register that file with the project. For information about creating and using resource bundles for an Oracle Fusion application, see About Customizing or Adding Resource Bundles.

The help text must use the following syntax:

<trans-unit>: Enter the topic ID. This must contain a unique prefix, the topic name, and the help type, either INSTRUCTION or DEFINITION.

Note:

The prefix must be unique. You must use this prefix for all your custom help strings.

For example:
```
MYCUSTHELP_NEWHELPTOPIC_DEFINITION
```
In this example, MYCUSTHELP is the prefix used to access the XLIFF file. NEWHELPTOPIC is the topic name, and DEFINITION is the type of ADF Faces help.

UI components access the help content based on the topic name. Therefore, if you use the same topic name for two different types of help (instruction and definition), then both types of help will be displayed by the UI component.
<source>: Create as a direct child of the <trans-unit> element and enter the help text.
<target>: Create as a direct child of the <trans-unit> element and leave it blank. This will hold translated text populated by translation tools.
<note>: Create as a direct child of the <trans-unit> element and enter a description for the help text.

Example 4-2 shows a resource file that contains two topics.

Example 4-2 XLIFF Resource Bundle

<?xml version="1.0" encoding="UTF-8" ?>
<xliff version="1.1" xmlns="urn:oasis:names:tc:xliff:document:1.1">
  <file source-language="en" original="this" datatype="xml">
    <body>
      <trans-unit id="MYCUSTHELP_NEWHELPTOPIC_DEFINITION">
        <source>Credit Card Definition</source>
        <target/>
        <note>This is the credit card definition text.</note>
      </trans-unit>
      <trans-unit id="MYCUSTHELP_NEWTOPIC2_INSTRUCTIONS">
        <source>Credit Card Instructions</source>
        <target/>
        <note>This is the credit card instruction text.</note>
      </trans-unit>
    </body>
  </file>
</xliff>

4.12.2 About Associating the Component with the Help Strings

In JDeveloper, select the component to display the help. Associate that component with the <trans-unit> element in the resource bundle, using the component's helpTopicID attribute. Ensure that the component supports the type of help (that is, definition or instruction) defined for the id attribute. For instructions, see the "How to Access Help Content from a UI Component" section of the Developing Web User Interfaces with Oracle ADF Faces.

4.13 About Customizing or Adding Resource Bundles

One method of customizing text is defining a new key in the resource bundle. There is a single override resource bundle for Oracle Fusion Applications. You can use this resource bundle to override values for existing keys, but you cannot add new keys.

Because you cannot define a new key in the shipped resource bundle, you need to create a new override bundle. You can accomplish this in JDeveloper by creating an XLIFF file from the New Gallery. After the file is generated, you can then enter new keys and their associated text in the XLIFF file.

To make the newly created resource bundle available for customization, you need to register the resource bundle with the customization project. You can do this from the Resource Bundle page of the Project Properties dialog.

You can also extend your application by creating a new resource bundle for a project if, for example, you want to customize the text for a label and you don't want to change the value in the global override bundle. To do this, create an XLIFF file from the New Gallery, package it into an ADF Library JAR file, and import the JAR file into the customization project.

Note:

All custom JAR file names must begin with the prefix Xx, for example XxMyJar.jar.

To test your customizations locally in JDeveloper Integrated WebLogic Server, you must also include the ADF Library JAR file in the APP-INF/lib directory.

For information about translating custom resource bundle strings, see About Translating Resource Bundles from an .

For more information about working with resource bundles, see the "Creating a Business Domain Layer Using Entity Objects" chapter in the Developing Fusion Web Applications with Oracle Application Development Framework.

4.14 About Extending Oracle Fusion Applications with a Custom Peer Application

Using JDeveloper, you can create a custom peer application to extend the functionality of an existing Oracle Fusion Applications module.

When you create the application, the package that you will use depends on how the functionality is integrated into the existing application.

If the new custom functionality is completely separate and loosely integrated into the existing application (for example, adding a custom button or link to an existing page to go to a new custom page that exposes the custom peer application), then you will need to create a new package and deploy it separately from the existing application. On the Name page (step 1 of 5) of the Create Fusion Web Application wizard, you can specify any application package prefix that you want, but do not use oracle.apps.cust.
If the new custom functionality is a tightly integrated extension of existing functionality (for example, adding new tasks to an existing task flow exposed in an existing page), then make sure that you specify oracle.apps.cust as the application package prefix on the Name page (step 1 of 5) of the Create Fusion Web Application wizard. In this case, the customization application workspace MAR will pick up your metadata files from the included ADF libraries when you package and deploy the customizations.

After you create the application workspace, create an ADF Library deployment profile for each project in the peer application. Then when you package the peer application, ADF Library JAR files will be generated.

After you have created and packaged your custom peer application, you will need to place the ADF library JAR files into the customization application workspace that you are extending. The ADF library JAR for model artifacts (such as entity objects and view objects) should be placed into the ExplodedEarDirectory/APP-INF/lib directory. The ADF Library JAR for user interface artifacts (such as pages) should be placed in the ExploadedWarDirectory/WEB-INF/lib directory. For more information about packaging and deploying, see About Deploying Customizations and Extensions.

When you extend an Oracle Fusion Applications module with a custom peer application, you must define a custom schema that contains all the database objects for the custom application. For more information, see About Customizing and Extending the Schemas.

4.15 About Deploying Oracle ADF Customizations and Extensions

After you have customized existing artifacts, you can use Oracle JDeveloper to deploy the customizations to a sandbox or to the Oracle Fusion application. For more information about how to use sandboxes to isolate changes from the mainline code so you can test and validate the changes, see the "Using Sandboxes" chapter in Oracle Cloud Extending Sales.

When you create a customization application workspace as described in Creating the Customization Application Workspace, the wizard generates a MAR profile. By default, the name of the MAR profile is application_name_customizations. It will automatically include the customizations that you implement. You can use this profile to package your customizations for deployment.

When you package customizations from the customization application workspace, the MAR file should include only library customizations. If you have extensions, make sure to include those directories as well (for example, oracle/apps), as shown in the following figure. Do not include the User Metadata or HTML Root Dir for Project in the MAR profile, unless explicitly directed to do so by product documentation.

Figure 4-1 MAR Deployment Profile Properties

If you extend your application with new custom artifacts, then you can use JDeveloper to package them into an ADF Library JAR and place them into the proper location within the application directory structure.

4.15.1 About Deploying the Customizations

You can use JDeveloper to deploy the customizations directly or you can use JDeveloper to create a MAR file, and then load the MAR file using WLST commands or the WebLogic Server Administration Console.

Tip:

You can also use Oracle Enterprise Manager Fusion Applications Control to import and export customization files. For more information, see the "Transferring Metadata Using Fusion Middleware Control" section of the Administering Oracle Fusion Middleware. The referenced procedure describes using Fusion Middleware Control, but also applies to Fusion Applications Control.

If you are using JDeveloper to deploy directly, you have a choice to deploy to available sandboxes or into the already deployed Oracle Fusion application.

When you deploy customizations on ADF Business Component objects (such as entity objects and view objects), the server must be restarted for the customizations to be picked up.

For instructions on deploying customizations, see the "How to Deploy New Customizations Applied to ADF LIbrary" section in the Developing Fusion Web Applications with Oracle Application Development Framework.

4.15.2 About Packaging New Artifacts into an ADF Library

If you have extended your application with new custom artifacts (or you are supplied with new artifacts), then you must package these artifacts into an ADF library JAR and place the JAR files in the proper location within the application.

Note:

All custom JAR files must begin with the prefix Xx, for example XxMyJar.jar.

The ADF library JAR for the new model artifacts (such as entity objects and view objects) should be placed into the ExplodedEarDirectory/APP-INF/lib directory (for example, /fusionapps/applications/fin/deploy/ EarFinPayables.ear/APP-INF/lib/XxMyJar.jar). The ADF Library JAR for the new user interface artifacts (such as pages) should be placed in the ExploadedWarDirectory/WEB-INF/lib directory.

For instructions on creating ADF Library, see the "Packaging a Reusable ADF Component into an ADF Library" section in the Developing Fusion Web Applications with Oracle Application Development Framework.