Skip Headers
Oracle® Fusion Applications Developer's Guide
11g Release 1 (11.1.3)

Part Number E15524-03
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

24 Using Extensible Flexfields

This chapter discusses how to use extensible flexfields to enable customers to add additional attributes to application business objects in Oracle Fusion Applications.

This chapter includes the following sections:

24.1 Introduction to Extensible Flexfields

An extensible flexfield is similar to a descriptive flexfield in that it provides a customizable expansion space that implementors, such as Oracle Fusion Applications customers, can use to configure additional attributes (segments) without additional programming. As with descriptive flexfields, each segment is represented in the database as a single column. However, with extensible flexfields the context values and context-sensitive segments are stored in a extension table.

Implementors can combine and arrange the segments into attribute groups that are tailored to a company's specific needs. For example, they can group related segments so that they appear together on the page. The attribute groups are referred to as contexts. You can optionally set up an extensible flexfield to enable implementors to group contexts into categories.

To understand how implementors use contexts and categories to configure extensible flexfields to meet a company's specific needs, see the "Using Flexfields for Custom Attributes" in the Oracle Fusion Applications Extensibility Guide.

To learn more about flexfield basics and terms, including developer and implementor roles, segments, and contexts, see Chapter 22, "Getting Started with Flexfields." For more details about the differences between descriptive flexfields and extensible flexfields, see Section 24.1.2, "The Benefits of Extensible Flexfields."

24.1.1 Understanding Extensible Flexfields

Extensible flexfields are comprised of the following key artifacts:

  • Contexts (attribute groups)

  • Context-sensitive segments

  • Logical pages

  • Categories

  • Category hierarchies

  • Usages

24.1.1.1 About Contexts (Attribute Groups)

An extensible flexfield context is a data grouping mechanism that implementors can use to arrange segments into meaningful groups. Each context is a group of attributes that displays in its own subregion of the user interface (UI) page at runtime. Implementors create and configure the contexts. After creating a context, an implementor must associate the context with the categories for which that group of attributes is relevant. For example, a Parts flexfield might have a Fax category and an All-in-One Printers category. A Fax context would be associated with both categories, while a Copy context would be relevant only to the All-in-One Printers category. You learn about categories in Section 24.1.1.4, "About Categories."

Figure 24-1 shows the UI page for the Positions business object. The Positions flexfield is embedded in the Additional Position Details region on the page. This region contains the Educational Requirements, Certification and License Requirements, and Travel contexts for the Positions flexfield.

Figure 24-2 and Figure 24-3 show UI pages for the Parts business object. The developer has enabled multiple categories for the Parts flexfield, so the page displays the category to which the part shown belongs. In Figure 24-2 the part belongs to the All-in-One Printers category, and in Figure 24-2 the part belongs to the Fax category. In these pages, the Parts flexfield is embedded in the Additional Information region. For the All-in-One Printers category in Figure 24-2, the Additional Information region contains the Copy, Fax, and Scan contexts for the Parts flexfield, while on the Parts page for the Fax category in Figure 24-3, the region contains just the Fax context.

Note:

A flexfield region is empty until the implementor configures the extensible flexfield that is embedded in it.

Extensible flexfields allow implementors to configure contexts as either single row or multiple row. That is, either one set of segments is stored for a business object instance, or multiple sets of segments are stored for the instance. For example, a position requires only one set of educational requirements, but can require more than one certificate or license.

For single-row contexts, the segments appear as fields in a form. With multiple-row contexts, the segments appear as columns in a table, thus allowing end users to capture a list. In Figure 24-1, Educational Requirements and Travel are single-row contexts, so end users can specify only a single value for each context-sensitive segment, such as the percent of travel time required for the position. The Certification and License Requirements context is a multi-row context, so end users can enter multiple rows, one for each certificate or license required for the position.

Figure 24-1 Position User Interface Page

Position user interface page

Figure 24-2 Parts User Interface Page for the All-in-One Printers Category

UI Page for All-in-One Printers Category

Figure 24-3 Parts User Interface Page for the Fax Category

Parts page for Fax category

24.1.1.2 Context-Sensitive Segments

With extensible flexfields, every segment is a member of a context (attribute group). That is, all segments are context-sensitive. Implementors define the contexts and their context-sensitive segments. Context-sensitive segments are the lowest-level data points that implementors can define for an extensible flexfield, and each segment is mapped to a column in an extension table. Just as with descriptive flexfields, the segments render as ADF Faces rich client (ADF Faces) components, such as text box, text area, list of values (LOV) choice list, date picker, checkbox, and radio button group.

In Figure 24-1, the Educational Requirements context contains the High School, Bachelor, Master, J.D., M.D., and Ph.D. context-sensitive segments, and the Certification and License Requirements context contains the Type and Certificate/License context-sensitive segments.

24.1.1.3 About Logical Pages

Extensible flexfields enable implementors to define logical pages with which to group contexts for display purposes. Each page can contain one or more contexts along with their respective context-sensitive segments. There is no limit to the number of contexts on a logical page. The implementors associate the logical pages with categories on a flexfield usage basis. You learn about usages in Section 24.1.1.6, "About Usages (Data Levels)."

In the Parts UI page shown in Figure 24-2, an implementor has defined two logical pages for this category — Printers and All-in-One. The implementor defined the Printers logical page to contain all contexts related to the printing capabilities of the printer, and the All-in-One page to contain all contexts related to the other capabilities of the printer, such as the scanning, copying, and faxing capabilities

The Parts page that is shown in Figure 24-2 displays the list of logical pages for the category in the left pane. End users view a logical page in the right pane by selecting it from the list. In this figure, the end user has chosen to view the All-in-One logical page. The Printers logical page is shown in Figure 24-4.

Figure 24-4 Printers Logical Page in the Parts User Interface Page

Printers logical page in the parts UI

Logical pages have several layout options. For example, in Figure 24-1, the developers chose to hide the entire left section because their customers will add attributes to a single page that is known at the time of development. However, in Figure 24-4, developers chose to display the list of logical pages in the left pane. For more information about layout options, see Section 24.6, "Employing an Extensible Flexfield on a User Interface Page."

24.1.1.4 About Categories

Categories enable applications to dynamically display different sets of logical pages and contexts at runtime. In the simplest case, you create a single category for a flexfield, and the same extensible flexfield contexts and logical pages appear for every instance of the business object. In some cases, you might need the application to display different sets of logical pages and contexts depending on a runtime differentiator, such as an instance value. In these cases, you can create multiple categories for the flexfield, or you can provide application-specific logic that enables implementors to define their own categories.

The Positions flexfield in Figure 24-1 has a single category. The same flexfield segments appear in the Additional Position Details region regardless of which position is displayed. In this page, the developer has hidden the name of the category, because there is only one category.

In Figure 24-2 and Figure 24-3 the segments that the region displays depend on which category the part belongs to. In Figure 24-2, the part belongs to the All-in-One Printers category and the UI displays fields related to copying, faxing, and scanning. In Figure 24-3, the part belongs to the Fax category and the UI displays fields related to only faxing.

24.1.1.5 About Category Hierarchies

You can choose to support multiple categories for your flexfield. When you do so, the extensible flexfield respects any hierarchical relationship that is defined for the categories, whether created by developers or defined by implementors. Figure 24-5 shows an example of categories that are defined in a hierarchical fashion. In this example, the root category (the category the does not have parents) is Computers and Office. One of its child categories is Printers and Ink. The Printers and Ink category, in turn, has a Printers child category. The Printers category has two children categories — All-in-One Printers and Single Function Printers.

Figure 24-5 Example of a Category Hierarchy

Example of a category hierarchy

Each child category inherits the contexts and pages from its parent categories. For example, the Printers category contains the Print, Printer Functions, and Supported Operating Systems contexts. The All-in-One Printers category inherits these contexts from the Printers category. It also inherits all logical pages that are defined for its parent categories. Additional contexts can be assigned directly to the All-in-One-Printers category, such as Copy and Scan, which are relevant only to All-in-One printers.

24.1.1.6 About Usages (Data Levels)

When you create an extensible flexfield, you create one flexfield usage for each set of tables in the application that uses the flexfield. In the simplest case, you will have one flexfield usage. For example, in Figure 24-1, the Positions application requires a single Positions table with its associated extension tables to store the extensible flexfield values. Implementors simply associate their contexts with that one usage to make them available to the Positions application.

When you have several objects in the application that should be extended using the same extensible flexfield, you need to create multiple usages for the flexfield. For example, in the case of an Items application there might be different data levels, such as items and item revisions. In this case, you create one usage per data level. By defining separate usages for each set of tables, you enable your implementors to reuse the same extensible flexfield configuration for all data levels.

24.1.2 The Benefits of Extensible Flexfields

When deciding whether to use a descriptive flexfield or an extensible flexfield to extend a business object, consider the following features that you make available for implementors by using extensible flexfields:

  • Custom grouping: Extensible flexfields enable implementors to group segments into contexts (attribute groups), and each context is displayed in its own region.

  • Multiple logical pages: When an implementor defines a large number of custom attributes, the implementor can choose to create several logical pages with which to display the attribute groupings. For example, Figure 24-2 and Figure 24-4 show different logical pages for the same part. In addition, the implementors can reuse these pages with different categories.

  • Hierarchical categories: Extensible flexfields can be configured to enable categories, which can be used to dynamically display different sets of logical pages and contexts based upon a runtime differentiator. The categories can be structured in a hierarchical manner and the children categories inherit all the contexts and logical pages that are configured for their parent categories.

  • Reusable attribute groups: When you enable multiple categories for an extensible flexfield, implementors can associate contexts with more than one category. When business object instances share common attributes, the implementors can put the common attributes in one context and reuse that context for in all applicable categories, thus minimizing set-up time. For example, in Figure 24-2 and Figure 24-3 the Fax context is associated with both the Fax category and the All-in-One Printers category.

  • Unlimited expansion space: While the number of segments that an implementor can define for a context is limited to the number of underlying flexfield extension columns, there is no limit to the number of contexts that an implementor can create for an extensible flexfield. Implementors can use the extension columns over and over in newly created contexts resulting in an unlimited number of custom attributes.

  • Custom lists: When implementors need to add custom lists to their business objects, they can create multiple-row contexts, which display the context's segments in a table, as shown in the Certification and License Requirements region in Figure 24-1.

  • Locale-specific values: You can optionally enable implementors to store different attribute values on a locale-by-locale basis. For example, an implementor could store and maintain the description of a part in English, Chinese, and French. The application displays and stores the value for the end user's locale.

    For more information, see the "Translating Flexfield and Value Set Configurations" section in the Oracle Fusion Applications Extensibility Guide.

Another advantage of using extensible flexfields is that you can create your own custom modeler classes for adding application-specific logic for generating ADF Business Components artifacts and UI task flows, as described in Section 24.8, "Customizing the Extensible Flexfield Modelers" and Section 24.8.2, "How to Customize the Runtime User Interface Modeler for Extensible Flexfields."

24.1.3 Extensible Flexfield Structure and Content

Unlike descriptive flexfields, which are mapped to extension columns in a product table, extensible flexfields are mapped to extension columns in extension tables that are separate from the product table. You create the extension tables at design time.

How Extensible Flexfields are Modeled in Oracle Application Development Framework

Extensible flexfields are modeled as a collection of Oracle Application Development Framework (ADF) polymorphic view rows, as described in the "Working with Polymorphic View Rows" section in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

The category hierarchy translates into a hierarchy of view objects that are configured to support polymorphic view rows. The view objects have view links to associated context view objects. A CategoryCode attribute acts as the discriminator that determines which category view row type should be used. At application runtime, the category in the base category view object row determines what pages and contexts are displayed. Given a collection of polymorphic view rows, each row can be a different type depending upon the category. An application module that holds the category view object is generated for each category.

Note:

Because flexfield view objects are modeled as polymorphic view objects, you can use extensible flexfield view objects in the same manner that you use any other polymorphic view objects, and they will behave in the same way.

24.2 Overview of Integrating Extensible Flexfields in an Application

The process of developing an extensible flexfield and integrating it in an application comprises several different activities, such as creating the extension tables, creating business components, and adding the flexfield to the appropriate application pages. This section identifies the major tasks for incorporating an extensible flexfield and points to the sections that provide the details for completing the tasks.

Before you begin:

Before you begin developing an extensible flexfield, you must first complete the following tasks:

  1. Identify the business object and related product table for which you are implementing the extensible flexfield. For example, you might want to enable implementors to create custom attributes for the Parts business object, which corresponds to the FND_CRM_PARTS table.

  2. Decide whether you want customers to be able to store translated values for one or more segments. For example, for a Parts flexfield, customers might want to store translations for the attributes in the Catalog Information context so they can print the catalog in different languages.

  3. Decide whether you want to enable customers to store the information for a context at different levels (also referred to as flexfield usages). For example, implementors might choose to set up a context for a Parts flexfield that has both a part supplier level and a part level. The same context segments appear in both the supplier UI and the part UI, but the end user would enter different values. Take, for example, a lead time segment. At the part level, the end user would supply the average lead time. At the supplier level, the end user would enter the actual lead time required for that supplier.

  4. Ascertain whether you need more than one set of artifacts generated for a flexfield usage. For example, you might need both private user interfaces that are based on updatable (entity based) view objects and public user interfaces that are based on read-only view objects. When you have more than one set of artifacts, you will need to define multiple groups at the entity-usage level for the flexfield usage, such as a Private group and a Public group, when you register the flexfield's business components.

  5. Determine whether you need to customize the generated model to add additional product-specific logic or customize the generated user interface (or both).

To complete the development tasks for an extensible flexfield:

  1. Create a base extension table for each flexfield usage. If you want to enable customers to store translations on a locale-by-locale basis, create a translation extension table and a view of the translation extension table for each usage as well.

    See Section 24.3, "Creating Extensible Flexfield Data Tables."

  2. Create the flexfield metadata. In this step, you use PL/SQL procedures to register the flexfield and its usages, create a default context data element, and register the flexfield data columns and root category.

    See Section 24.4, "Defining and Registering Extensible Flexfields."

  3. Create and configure business components to support the extensible flexfield. In this step, you create an entity object and a view object over the base extension table, and, if they exist, the translation extension table and view. You then create the base category view object over the product table entity object (the table for which the flexfield is an extension). If you want to enable search capabilities, you create a declarative view object for searching over the product table that the flexfield extends. Last, you configure the flexfield usages' application modules to support flexfields and you register the flexfield's business components.

    See Section 24.5, "Defining and Registering Extensible Flexfield Business Components."

  4. Add the extensible flexfield to the appropriate UI pages.

    See Section 24.6, "Employing an Extensible Flexfield on a User Interface Page."

  5. Load any necessary application seed data, such as error messages and lookup values.

    See Section 24.7, "Loading Seed Data."

  6. Optionally, customize the generated model or the generated UI artifacts (or both).

    See Section 24.8, "Customizing the Extensible Flexfield Modelers" and Section 24.8.2, "How to Customize the Runtime User Interface Modeler for Extensible Flexfields."

  7. Test the flexfield.

    See Section 24.9, "Testing the Flexfield."

After you have completed the extensible flexfield development process and delivered your application, implementors can use the Manage Extensible Flexfields task flow to define contexts, categories, and pages, and to configure the segments for each extensible flexfield. These task flows determine how the flexfield's segments will be populated, organized, and made available to end users within the application. For information about planning and implementing flexfield configuration, such as defining attributes, labels, behavior, and associated value sets, see the "Using Flexfields for Custom Attributes" chapter in the Oracle Fusion Applications Extensibility Guide.

Note:

An extensible flexfield is not displayed at runtime unless at least one context and context-sensitive segment has been configured and associated with a category.

To make the Manage Extensible Flexfields task flow available to application implementors, register it with Oracle Fusion Functional Setup Manager. For more information, see Section 26.5, "Integrating Flexfield Task Flows into Oracle Fusion Functional Setup Manager".

24.3 Creating Extensible Flexfield Data Tables

Before you can define an extensible flexfield, you must create one set of dedicated database tables for each of the flexfield's usages. Each set must be composed of at least a base extension table. If you want to enable customers to store translated values for the segments, the set must include a translation extension table and a view of the translation extension table. An extensible flexfield must have at least one set of tables, which defines the master usage. The implementors will expose only the extension columns that they require.

Note:

The steps in this section assume that the product table that the flexfield is extending already exists.

24.3.1 How to Create Extensible Flexfield Database Tables

Each flexfield usage requires a base extension table. This table stores nontranslatable contexts and their segment values. The table name should have a suffix of _B to identify it as the base extension table.

Table 24-1 lists the fields that you must include in a base extension table. You can include additional columns, such as columns that are required by application standards.

Add as many attribute columns as you feel is necessary. The attribute columns can be of type VARCHAR2, NUMBER, and TIMESTAMP. Do not set scale or precision for the NUMBER columns. There are no size requirements for the VARCHAR2 columns. To avoid compatibility and interoperability problems, name the columns ATTRIBUTE_type-and-number, such as ATTRIBUTE_CHAR1 for a VARCHAR2 column, ATTRIBUTE_NUMBER1 for a NUMBER column, and ATTRIBUTE_TIMESTAMP1 for a TIMESTAMP column.

For columns of type NUMBER, you can optionally add a column named ATTRIBUTE_NUMBERn_UOM to store the unit of measure.

The primary key of the base extension table must include the EFF_LINE_ID column, the CONTEXT_CODE column, the CATEGORY_CODE column, and the columns that match the primary key columns of the product table.

If you plan to allow customers to store translations for some contexts on a locale-by-locale basis, then you must also create a translation extension table and a view over the translation extension table. The translation extension table and the translation extension view are not required. However, if you do not provide these tables, the customers cannot store translations for their extensible flexfields as described in the "Translating Custom Text" chapter in the Oracle Fusion Applications Extensibility Guide. For more information about multi-language tables, see Section 9.2, "Using Multi-Language Support Features."

At runtime, as end users enter attribute values for each context, the context and its segment (attribute) values are stored as a row in the base extension table if the context is not translatable, or, if the context is translatable, as rows in the translation extension table (one row per installed language). The translation extension view returns the rows in the current user locale. When an implementor creates a translatable context, the implementor can add only VARCHAR2 segments to the context.

Note that unlike typical translation tables, the base extension table is completely separate from the translation extension table. All the segment values for a context go in either the base extension table or in the translation extension table. If a context is marked as translatable, all segment values are stored in the translation extension table, otherwise they are stored in the base extension table.

Table 24-2 lists the required translation extension table columns and Table 24-3 lists the required translation extension view columns. You can include additional columns, such as columns that are required by application standards.

The translation table name should have a suffix of _TL to identify it as a translation table, and the name of the view of the translation table should have a suffix of _VL.

The primary key of the translation extension table must include the EFF_LINE_ID column, the CONTEXT_CODE column, the CATEGORY_CODE column, the LANGUAGE column, and the columns that match the primary key columns of the product table.

Developers typically create the same number of VARCHAR2 type attribute columns in the translation extension table as exist in the base extension table, but you are not required to do so. Create as many VARCHAR2 type attribute columns as you think are necessary for a translatable context. To avoid compatibility and interoperability problems, name the columns ATTRIBUTE_CHARnumber, such as ATTRIBUTE_CHAR1, ATTRIBUTE_CHAR2, and so forth. When setting the size of the VARCHAR2 columns in an extension translation table, consider that the columns might need to contain multibyte characters.

You must use the Database Schema Deployment Framework tools to create the tables and columns. Using these tools ensures that the table and its columns are registered in the Oracle Fusion Middleware Extensions for Applications (Applications Core) data dictionary. For more information, see Chapter 57, "Using the Database Schema Deployment Framework."

Note:

To avoid compatibility and interoperability problems, format the column names as indicated.

Table 24-1 Extensible Flexfield Base Extension Table (_B) Specification

Column Type Nullable?

EFF_LINE_ID

NUMBER(18)

No

Primary key columns of the product table for which this extensible flexfield is being defined.

Same as the column in the application.

No

CONTEXT_CODE

VARCHAR2(80)

No

CATEGORY_CODE

VARCHAR2(80)

No

CREATED_BY

VARCHAR2(64)

No

CREATION_DATE

TIMESTAMP(6)

No

LAST_UPDATED_BY

VARCHAR2(64)

No

LAST_UPDATE_DATE

TIMESTAMP(6)

No

LAST_UPDATE_LOGIN

VARCHAR2(32)

Yes

ATTRIBUTE_CHAR1

VARCHAR2(150)

Yes

...

   

ATTRIBUTE_CHAR40

VARCHAR2(150)

Yes

ATTRIBUTE_NUMBER1

NUMBER

Yes

ATTRIBUTE_NUMBER1_UOM

VARCHAR2(9)

Yes

....

   

ATTRIBUTE_NUMBER20

NUMBER

Yes

ATTRIBUTE_NUMBER20_UOM

VARCHAR2(9)

Yes

ATTRIBUTE_TIMESTAMP1

TIMESTAMP

Yes

...

TIMESTAMP

Yes

ATTRIBUTE_TIMESTAMP10

TIMESTAMP

Yes


Table 24-2 Extensible Flexfield Translation Extension Table (_TL) Specification

Column Type Nullable?

EFF_LINE_ID

NUMBER(18)

No

Primary key columns of the product table for which this extensible flexfield is being defined.

Same as the column in the application.

No

CONTEXT_CODE

VARCHAR2(80)

No

CATEGORY_CODE

VARCHAR2(80)

No

CREATED_BY

VARCHAR2(64)

No

CREATION_DATE

TIMESTAMP(6)

No

LAST_UPDATED_BY

VARCHAR2(64)

No

LAST_UPDATE_DATE

TIMESTAMP(6)

No

LAST_UPDATE_LOGIN

VARCHAR2(32)

Yes

SOURCE_LANG

VARCHAR2(4)

No

LANGUAGE

VARCHAR2(4)

No

ATTRIBUTE_CHAR1

VARCHAR2(1000)

Yes

...

VARCHAR2(1000)

Yes

ATTRIBUTE_CHAR40

VARCHAR2(1000)

Yes


Table 24-3 Extensible Flexfield Translation Extension View (_VL) Specification

Column Type Nullable?

EFF_LINE_ID

NUMBER(18)

No

Primary key columns of the product table for which this extensible flexfield is being defined.

Same as the column in the application.

No

CONTEXT_CODE

VARCHAR2(80)

No

CATEGORY_CODE

VARCHAR2(80)

No

ATTRIBUTE_CHAR1

VARCHAR2(1000)

Yes

...

   

ATTRIBUTE_CHAR40

VARCHAR2(1000)

Yes


24.4 Defining and Registering Extensible Flexfields

After you create a set of dedicated tables for a flexfield's usage, use procedures from the FND_FLEX_DF_SETUP_APIS PL/SQL package to register the flexfield usage and define its metadata in seed tables.

The definition of an extensible flexfield usage includes the following information:

After the implementors configure the flexfield, the definition of an extensible flexfield also contains the following information:

24.4.1 How to Register Extensible Flexfields

Use the FND_FLEX_DF_SETUP_APIS PL/SQL API package to register new extensible flexfield usages and to add the specified flexfield metadata to the following global configuration metadata.

  • FND_DF_FLEXFIELDS_B, FND_DF_FLEXFIELDS_TL

    Add the extensible flexfield's code name to both tables.

  • FND_DF_FLEX_USAGES_B, FND_DF_FLEX_USAGES_TL

    Add the extensible flexfield usages.

  • FND_DF_FLEX_USAGES_TL

    Add the display names for the flexfield usages.

  • FND_DF_TABLE_USAGES

    For each usage, add the product table name for which the flexfield is implemented and set the table type to BASE. Also add the usage's base extension table name with a type of EXTENSION, and add the usage translation extension table name with a type of EXTENSION_TL. Set the table usage code to the flexfield's usage code.

    If the consumers want to support interface loading of extensible flexfield data, also add entries for the BASE_INTERFACE, EXTENSION_INTERFACE, and EXTENSION_INTERFACE_TL table types.

  • FND_DF_SEGMENTS_B

    Add one row for the extensible flexfield with CONTEXT_CODE set to "Context Data Element" and SEGMENT_CODE set to "Context Segment."

  • FND_FF_COLUMN_USAGES

    For each usage, add an entry for each context-specific column in the EXTENSION and EXTENSION_TL tables. For example, add entries for all the ATTRIBUTE_CHARn columns, for all the ATTRIBUTE_NUMBERn columns, and so forth.

  • FND_EF_CATEGORIES_B

    An extensible flexfield requires at least one entry in this table. Add additional entries only if you are shipping your application with some categories already defined.

    Note:

    The CATEGORY_CODE and PARENT_CATEGORY_CODE values are used in the flexfield's element in the XML schema for web services. The use of leading numeric characters, spaces, underscores, and multibyte characters, which are all encoded in XML schemas, make the code in the schema element difficult to read.

After you create the flexfield's business components, you must complete the registration process by adding entity details, as described in Section 24.4.1, "How to Register Extensible Flexfields." You must have at least one entity usage per base extension table. If you require parallel sets of extensible flexfield artifacts generated for different uses (for example, public view objects and private view objects), replicate the entity usage entries with a different group name. When the business components are generated for the flexfield, a separate set of components are generated for each group.

For more information, refer to the package specification.

24.5 Defining and Registering Extensible Flexfield Business Components

To incorporate an extensible flexfield into your application, you must define and configure entity objects and view objects for each set of extension tables that are defined for each flexfield usage.

Figure 24-6 shows the extensible flexfield business components for a product table. In this example, the flexfield is not translatable. The developer creates an entity object and view object over the base extension table to support contexts.

If the flexfield is translatable, the developer would also create an entity object and view object over the translation extension table and the translation extension view.

When an implementor deploys flexfield configurations, the deployment process creates the extended context entity objects, context view objects, category view objects, and category-to-context view links. Notice that in this example, the C2 context is a member of two categories.

Figure 24-6 Extensible Flexfield Business Components

Extensible flexfield business components

To define an extensible flexfield business component:

  1. Create and configure extensible flexfield entity objects over the base extension table. If a translation extension table exists for the flexfield, create and configure extensible flexfield entity objects over the translation extension table and the translation table view.

  2. Configure the EFF_LINE_ID attribute for each extensible flexfield entity object as a unique ID.

  3. Create and configure flexfield view objects to support contexts, categories, and, optionally, searching.

  4. For each extensible flexfield usage, configure its application module to support extensible field usage by adding a createDetailRowIfNotExist method.

  5. Register the flexfield business components.

Tip:

After completing these steps, you can regenerate the flexfield business components programmatically at runtime to update your extensible flexfield implementation without manual intervention.

For more information, see Section 26.4, "Regenerating Flexfield Business Components Programmatically."

24.5.1 How to Create and Configure Extensible Flexfield Entity Objects

For each extensible flexfield usage, you must create entity objects over the base extension table. If you created a translation extension table and a translation extension view for a usage, you must create entity objects for them as well.

For more information about creating entity objects, see the "Creating a Business Domain Layer Using Entity Objects" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

Note:

The packages in which these entity objects are created must not fall under the packages allocated for runtime generated business components (which are specified in adf-config.xml and the flexfield usage metadata).

Before you begin:

  1. Create one set of dedicated extension tables per usage, as described in Section 24.3.1, "How to Create Extensible Flexfield Database Tables."

  2. Register the flexfield's usages as described in Section 24.4.1, "How to Register Extensible Flexfields."

  3. Ensure that the Applications Core library has been added to the data model project, as described in Section 3.3, "Adding the Applications Core Library to Your Data Model Project."

  4. Verify that at least one customization class is included in adf-config.xml. This serves to ensure correct application behavior. It does not matter which customization class you include.

    For information about defining the customization layers, see the "Understanding Customization Layers" section in the Oracle Fusion Applications Extensibility Guide.

24.5.1.1 Creating and Configuring an Entity Object Over the Base Extension Table

For each extensible flexfield usage, use the standard wizard to create an entity object over the base extension table that is described in Table 24-1, but apply the changes described in the following procedure to support the extensible flexfield.

To create and configure an entity object over the base extension table: 

  1. On the Attributes page of the wizard, include only the following columns as attributes in your new entity object:

    • EFF_LINE_ID

    • OBJECT_VERSION_NUMBER

    • Primary key columns of the product table

    • CONTEXT_CODE

    • CATEGORY_CODE

    • CREATED_BY

    • CREATION_DATE

    • LAST_UPDATED_BY

    • LAST_UPDATE_DATE

    • LAST_UPDATE_LOGIN

  2. On the Attribute Settings page, do the following:

    • Set the EFF_LINE_ID attribute to be a unique primary key.

    • Set the CONTEXT_CODE attribute to be a discriminator, with a default value of 0.

  3. On the Java page, confirm that the objectnameBEOImpl entity object class to be generated extends oracle.apps.fnd.applcore.oaext.model.OAEntityImpl.

  4. After creating the entity object, configure all of its attributes to be hidden.

    On the UI Hints tab of the Property Inspector for each attribute, set the Display Hint property to Hide.

24.5.1.2 Creating and Configuring an Entity Object Over the Translation Extension Table

If you created a translation extension table for the flexfield usage, as described in Table 24-2, use the standard wizard to create an entity object over the translation extension table, but apply the changes described in the following procedure to support the extensible flexfield.

To create and configure an entity object over the extensible flexfield translation extension table: 

  1. On the Attributes page of the wizard, include only the following columns as attributes in your new entity object:

    • EFF_LINE_ID

    • OBJECT_VERSION_NUMBER

    • Primary key columns of the product table

    • CONTEXT_CODE

    • CATEGORY_CODE

    • SOURCE_LANG

    • LANGUAGE

    • CREATED_BY

    • CREATION_DATE

    • LAST_UPDATED_BY

    • LAST_UPDATE_DATE

    • LAST_UPDATE_LOGIN

  2. On the Attribute Settings page, do the following:

    • Set the EFF_LINE_ID attribute to be a unique primary key.

    • Set the CONTEXT_CODE attribute to be a discriminator, with a default value of 0.

  3. On the Java page, confirm that the objectnameTlEOImpl entity object class to be generated extends oracle.apps.fnd.applcore.oaext.model.OAEntityImpl.

  4. After creating the entity object, configure all of its attributes to be hidden.

    On the UI Hints tab of the Property Inspector for each attribute, set the Display Hint property to Hide.

  5. Configure all of the non-key attributes that are of type String to be translatable.

    On the Applications tab of the Property Inspector for each non-key, String type attribute, set the OA Translatable property to True.

24.5.1.3 Creating and Configuring an Entity Object Over the Translation Extension View

If you created a translation extension table and view for the flexfield usage, use the standard wizard to create an entity object over the translation extension view that is described in Table 24-3, but apply the changes described in the following procedure to support the extensible flexfield.

To create and configure an entity object over the extensible flexfield translation extension view: 

  1. On the Attributes page of the wizard, include only the following columns as attributes in your new entity object:

    • EFF_LINE_ID

    • Primary key columns of the product table

    • CONTEXT_CODE

    • CATEGORY_CODE

  2. On the Attribute Settings page, do the following:

    • Set the EFF_LINE_ID attribute to be a unique primary key.

    • Set the CONTEXT_CODE attribute to be a discriminator, with a default value of 0.

  3. On the Java page, confirm that the objectnameVlEOImpl entity object class to be generated extends oracle.apps.fnd.applcore.oaext.model.OAEntityImpl.

  4. After creating the entity object, configure all of its attributes to be hidden.

    On the UI Hints tab of the Property Inspector for each attribute, set the Display Hint property to Hide.

  5. On the Applications tab of the Property Inspector for the entity object General tab, set the OA Base Table property to the name of the view underlying this entity object.

24.5.2 How to Configure the EFF_LINE_ID Attribute as a Unique ID

After you create and configure entity objects over the base extension table, translation extension table, and view of the translation extension table as described in Section 24.5.1, "How to Create and Configure Extensible Flexfield Entity Objects," you must configure the EFF_LINE_ID attribute for each entity object as a unique ID.

The Unique ID Generator provides a way for your application to generate unique IDs for entity object attributes of type BigDecimal. The unique IDs generated are also of type BigDecimal, and meet certain required criteria for uniqueness across database instances.

To configure EFF_LINE_ID as a unique ID:

  1. Create a connection to the database that contains the Unique ID Generator table called S_ROW_ID.

  2. Configure a special default-value expression for EFF_LINE_ID that will invoke the Unique ID Generator when needed.

For more information, see Section 9.6, "Using Unique ID."

24.5.3 How to Create and Configure Extensible Flexfield View Objects

For each extensible flexfield usage, use the standard wizard (not the Flexfield Business Components wizard) to create the following types of view objects:

  • To support contexts for the extensible flexfield, create one view object over the base extension table entity object and, if the flexfield has a translation extension table, one view object over the translation extension view entity object.

    Note:

    No view objects are required over the translation table entity object.

  • To support categories for the flexfield, create a view object over the product table entity object for which you are developing this extensible flexfield.

  • To support searching, create declarative view objects.

For more information about creating view objects, see the "Defining SQL Queries Using View Objects" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

Before you begin:

  1. Create and configure entity objects over the base extension table, translation extension table, and view as described in Section 24.5.1, "How to Create and Configure Extensible Flexfield Entity Objects."

  2. Configure the EFF_LINE_ID attribute as a unique ID as described in Section 24.5.2, "How to Configure the EFF_LINE_ID Attribute as a Unique ID."

24.5.3.1 Creating and Configuring Context View Objects

To support contexts for an extensible flexfield usage, the usage must have a view object over its base extension table entity object. If you created a translation extension table for the usage, you must also create a view object over the translation extension view entity object.

To create and configure context view objects: 

  1. Create the view objects over the base extension table entity object and, if you created a translation extension table for the usage, over the translation extension view entity object in the usual manner.

  2. On the Java page for each view object, ensure that the view object classes to be generated extend base classes as follows:

    • vo_nameImpl extends EFFViewObjectImpl

    • vo_nameRowImpl extends EFFViewRowImpl

    • vo_nameDefImpl extends EFFViewDefImpl

    These base classes are in the oracle.apps.fnd.applcore.oaext.model package.

24.5.3.2 Creating and Configuring the Category View Object

To support categories for the flexfield, there must be a view object over the product table entity object for which you are developing the extensible flexfield.

To create and configure the category view object: 

  1. Create a view object over the product table for which you are implementing the extensible flexfield in the usual manner. For example, in Figure 24-2, the product table is the Parts table that stores the base attributes for the Parts entity, such as Part Number, Description, and Unit Cost.

    This view object must include an attribute called CategoryCode, which is used to identify the category to which each row of data belongs. This attribute must be an entity-based attribute of type VARCHAR2 with a maximum of 80 characters.

    Set the CategoryCode attribute to be a discriminator, with a default value of 0.

    You must ensure that the correct category code is returned for this attribute at runtime.

  2. Implement the following interface on the Java tab of the view object definition:

    oracle.apps.fnd.applcore.oaext.model.EFFCategoryViewObjectInterface
     
    

    Create a method called queryCategoryRowByPrimaryKey that accepts up to five primary key values and returns the correct row of the product view object as demonstrated in Example 24-1.

    For this example, the view object has a view criteria defined, which is called getItemByKey, and has bind parameters defined for two primary key attributes, which are called OrganizationIdBind and InventoryItemIdBind.

    Example 24-1 Query Category Row Method

    public Row queryCategoryRowByPrimaryKey(
      String pk1, String pk2, String pk3, 
      String pk4, String pk5)
        {
            Long invId = new Long (pk1);
            Long orgId = new Long (pk2);
     
            setWhereClauseParams(null);
            applyViewCriteria(null);
     
            ViewCriteria vc = getViewCriteria("getItemByKey");
            setNamedWhereClauseParam("OrganizationIdBind", orgId);
            setNamedWhereClauseParam("InventoryItemIdBind", invId);
    
            applyViewCriteria(vc);
            executeQuery();
            Row r = null;
            if(hasNext())
            {
              r = next();
              setCurrentRow(r);
            }
            return r;
        }
     
    

    This method queries the correct category row based on up to five primary key values passed into the method.

24.5.3.3 Creating a Declarative View Object to Enable Searching

To enable searching, there must be a declarative view object for searching over the product table for which you are implementing the extensible flexfield.

To create a declarative view object to enable searching: 

  1. Create a declarative view object in the usual manner.

  2. On the Java page, confirm that the objectnameVOImpl view object class to be generated extends the following class:

    oracle.apps.fnd.applcore.oaext.model.EFFCategoryViewObjectImpl
     
    

    The EFFCategoryViewObjectImpl class adds the additional WHERE clause that provides security.

24.5.4 How to Configure an Extensible Flexfield Application Module

To enable UI pages that contain a flexfield usage to display the flexfield's segments, you must configure an application module to support that flexfield usage.

You can use the application module that you have already created for your application, or you can use the standard wizard to create a new application module dedicated to your extensible flexfield.

To the application module's Java client interface, add a method called createDetailRowIfNotExist, as shown in Example 24-2.

Example 24-2 Java Source for createDetailRowIfNotExist Method

public void createDetailRowIfNotExist(
  String categoryAMInstName, String categoryViewUsageName, 
  String contextViewLinkAccName, String category_pk1, 
  String category_pk2, String category_pk3, 
  String category_pk4, String category_pk5)
{
  EffCategoryAMImpl effAM = (EffCategoryAMImpl) 
    findApplicationModule(categoryAMInstName);
  effAM.createDetailRowIfNotExist(
    categoryViewUsageName, contextViewLinkAccName, 
    category_pk1, category_pk2, category_pk3, 
    category_pk4, category_pk5);
}
 

When an implementor deploys a configured extensible flexfield, a personalization is created on this application module, and an application module instance is generated for each category that the implementor defined for the flexfield. For information about deploying flexfields, see the "Deploying Flexfield Configurations" section in the Oracle Fusion Applications Extensibility Guide.

24.5.5 How to Register the Extensible Flexfield Business Components

After you configure business components to support an extensible flexfield usage, you must complete the flexfield registration process by providing the names of the flexfield usage's entity object and view object. If you created a translation extension table for the flexfield usage, you must also register the entity object over the translation extension table.

You use procedures from the FND_FLEX_DF_SETUP_APIS PL/SQL package to register the flexfield usage's entity details. For information about using the procedures, refer to the package specification.

To register extensible flexfield entity details:

Add the flexfield metadata to the FND_DF_ADFBC_USAGES table as specified by the package specification.

For each table defined in FND_DF_TABLE_USAGES, specify the name of the entity object and view object. For the translation extension table, also specify the name of the entity object over the translation extension table.

If the consumers who are incorporating the flexfield into the application want to generate a different set of artifacts for both private and public groups, create an additional set of rows with a different extensible flexfield group name.

Figure 24-7 shows example entries for a flexfield usage. As described in Section 24.4.1, "How to Register Extensible Flexfields," the FND_DF_TABLE_USAGES table contains rows for the product table (USGA_BASE), the usage base extension table (USGA_EFF_B), and the usage translation extension table (USGA_EFF_TL). The FND_DF_ADFBC_USAGES table contains two entries for each entry in the FND_DF_TABLE_USAGES table — one for the Private group and one for the Public group. Each row names the entity object and the view object. The rows for the translation extension table also name the entity object over the translation extension table. Note that not all columns are shown.

Note:

In this example, the Public group is necessary because the product that is using the flexfield usage requires a parallel set of extensible flexfield artifacts generated for public view objects.

If the consumers wanted to support interface loading of extensible flexfield data, you would also add entries for the BASE_INTERFACE, EXTENSION_INTERFACE, and EXTENSION_INTERFACE_TL table types.

Figure 24-7 Example Entity Detail Entries

Example entity table details

24.6 Employing an Extensible Flexfield on a User Interface Page

You can incorporate an extensible flexfield into an application with several UI variations:

For more information about task flows, see the "Creating a task Flow" section in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

Note:

When it is not clear what type of data will be configured for the extensible flexfield, name the containing region, such as a page or a dialog, "Additional Information" or "Additional Information: Object Name" for view-only data, and "Edit Additional Information" or "Edit Additional Information: Object Name" for editable data. If the containing region is a tab, name the tab "Additional Information" or "Edit Additional Information," as appropriate. This convention ensures consistency across Oracle Fusion applications.

24.6.1 How to Expose the Logical Pages and Contexts Associated with One Extensible Flexfield Usage

You can incorporate an extensible flexfield into the UI as a list of the logical pages for a single usage, combined with the contexts for the selected logical page, and integrated into a single task flow.

To expose the logical pages and contexts that are associated with one extensible flexfield usage:

  1. Create a task flow for the single extensible flexfield usage, which includes a page fragment with a splitter that contains the list of the usage's logical pages on the left, and the contexts associated with the selected logical page on the right.

  2. Add the task flow to the page.

  3. Render the page.

24.6.1.1 Creating a Task Flow for a Single Extensible Flexfield Usage

Create a task flow to be added to the page that will display the page lists and contexts.

Before you begin: 

Create and configure business components to support the extensible flexfield as described in Section 24.5, "Defining and Registering Extensible Flexfield Business Components."

To create the task flow: 

  1. Create a task flow.

  2. Add a view activity for a new page fragment and designate the activity as the default activity.

  3. Add an EffCategoryPagesBean managed bean with the class oracle.apps.fnd.applcore.flex.eff.runtime.EffCategoryPagesBean to the task flow. The scope should be pageFlow.

  4. Open the fragment and drag and drop a splitter control.

  5. On the first facet, drag and drop the EffCatPageListContainer seeded task flow from the ViewController FlexModeler-View library.

  6. Add the following parameters:

    • _eff_application_id: Provide the FND_EF_UI_PAGES_B.APPLICATION_ID value; for example 10010

    • _eff_descriptive_flexfield_code: Provide the FND_EF_UI_PAGES_B.DESCRIPTIVE_FLEXFIELD_CODE value; for example EGO_ITEM_EFF

    • _eff_category_code: Provide the FND_EF_UI_PAGES_B.CATEGORY_CODE value; for example ELECTRONICS

    • _eff_usage_code: Provide the FND_EF_UI_PAGES_B.FLEXFIELD_USAGE_CODE value; for example, EGO_ITEM_DL

    • _eff_containerBean: Provide #{pageFlowScope.EffCategoryPagesBean}

  7. On the first facet, drag and drop the EffContextPageContainer seeded task flow from the ViewController FlexModeler-View library.

  8. Add the following parameters:

    • _eff_application_id: Provide #{pageFlowScope._eff_application_id}

    • _eff_descriptive_flexfield_code: Provide #{pageFlowScope._eff_descriptive_flexfield_code}

    • _eff_category_code: Provide #{pageFlowScope._eff_category_code}

    • _eff_usage_code: Provide #{pageFlowScope._eff_usage_code}

    • _eff_page_code: Provide #{pageFlowScope._eff_page_code}

    • _eff_containerBean: Provide #{pageFlowScope.EffCategoryPagesBean}

    • _eff_category_pk1: (optional) Provide the value for the category's first primary key column, if applicable. For example if the first primary key column is INVENTORY_ITEM_ID, and its value is 149, provide 149.

    • _eff_category_pk2 - (optional) Provide the value for the category's second primary key column, if applicable. For example if the second primary key column is ORGANIZATION_ID, and its value is 204, provide 204.

    • _eff_category_pk3 through pk5: Provide the value for that primary key column, if applicable

24.6.1.2 Adding the Task Flow to the UI Page

Add the task flow for the extensible flexfield usage to the UI page that will display the logical page lists and contexts.

Before you begin: 

Create the task flow for the extensible usage as described in Section 24.6.1.1, "Creating a Task Flow for a Single Extensible Flexfield Usage."

To add the task flow to the page: 

  1. Open the .jspx page that will display the logical page lists and contexts.

  2. Drop the task flow on the page.

24.6.1.3 Rendering the Page

Render the page to view the UI.

Before you begin: 

To render the page: 

  1. Open the Databindings.cpx file for the project that is consuming the generated extensible flexfield task flows and add the following EFFRuntimeAM data control:

    <BC4JDataControl      id="EFFRuntimeAMDataControl"
                          Package="oracle.apps.fnd.applcore.flex.eff.
                            runtime.applicationModule"
                          FactoryClass="oracle.adf.model.bc4j.
                            DataControlFactoryImpl"
                          SupportsTransactions="true" SupportsFindMode="true"
                          SupportsRangesize="true" SupportsResetState="true"
                          SupportsSortCollection="true" Configuration=
                            "EFFRuntimeAM"
                          syncMode="Immediate"
                          xmlns="http://xmlns.oracle.com/adfm/datacontrol"/>
    
  2. Complete the following steps to mark the flexfield usage's package directory as a flexfield model package:

    1. Create an inf directory in the flexfield usage's package directory. For example, if the usage's package is oracle.apps.fnd.applcore.crmdemo.flex, then create the /oracle/apps/fnd/applcore/crmdemo/flex/inf directory.

    2. To identify the package directory as a flexfield model package, create a file named FlexfieldPkgInf.xml in the package's inf directory and add the following contents to the file.

      <?xml version="1.0" encoding="UTF-8" ?>
      <flexfield-inf/>
      

      Note:

      Ensure that this directory contains only the automatically generated flexfield MDS files and the inf directory with the FlexfieldPkgInf.xml file. When the application is deployed, the ANT script that is run by the deployment process will add the required name spaces for the identified package directory to the adf-config file, as shown in the following example.

      <namespace path="/persdef" metadata-store-usage="mdsRepos"/>
      <namespace path="/oracle/apps/scm/productCatalogManagement/items/protectedModel/itemRevisionEff"metadata-store-usage="mdsRepos"/>
      <namespace path="oracle/apps/scm/productCatalogManagement/"items/protectedModel/itemsEffmetadata-store-usage="mdsRepos"/>
      
  3. Complete the following steps to identify the flexfield user interface packages:

    1. Either create a web application archive (WAR) deployment profile in the project that is named FlexfieldViewController and that contains flexfield user interface packages, or reference the flexfield user interface packages through a library Java archive (JAR) file. Do not include this deployment profile in the application enterprise archive (EAR) file. This is only a marker profile.

    2. Find the flexfield user interface package directory under the ViewController/public_html directory and add an inf subdirectory to the flexfield user interface package directory.

    3. To identify the package directory as a flexfield user interface package, create a file named FlexfieldViewPkgInf.xml in the package's inf directory and add the following contents to the file.

      <?xml version="1.0" encoding="UTF-8" ?>
      <flexfield-inf/>
      

      Note:

      The package directory will be added to the adf-config file and thus should contain only the automatically generated flexfield MDS files and the inf directory with this file.

      Do not repeat these steps for the corresponding pageDefs packages under Application Sources. Those packages are added automatically when the flexfield is deployed.

  4. Add the following snippet to the Application tag at the top of the Databindings.cpx file in order for the application to find the page definitions for the generated UI artifacts:

    PageMapClass="oracle.jbo.uicli.mom.DynamicPageMapImpl"
                 BasePageDefPackageName="pageDefs"
    
  5. Deploy and run the application to render the page.

24.6.2 How to Expose the Complete Set of an Extensible Flexfield's Usages, Logical Pages, and Associated Contexts

To expose the complete set of usages, logical pages, and associated contexts, build a UI page that is comprised of a splitter with two task flows: one containing the list of extensible flexfield usages and their associated logical pages on the left, and the other containing the contexts associated with the selected logical page on the right.

To build the UI page: 

  1. Create a task flow for the extensible flexfield usages and a task flow for the associated contexts.

  2. Create the left and right fragment pages.

  3. Use the task flows in the UI page.

24.6.2.1 Creating the Task Flows

The UI page requires two task flows: one containing the list of extensible flexfield usages and their associated logical pages, and the other containing the contexts associated with the selected logical page.

Before you begin: 

Create and configure business components to support the extensible flexfield as described in Section 24.5, "Defining and Registering Extensible Flexfield Business Components."

To create the two task flows: 

  1. Create a page-list task flow, for example, PageListTF.

  2. Add the following parameter to the task flow:

    • Name: ContainerBean

    • Class: oracle.apps.fnd.applcore.flex.eff.runtime.EffCategoryPagesBean

    • Value: #{pageFlowScope.ContainerBean}

  3. Create the context container task flow, for example, ContextPageTF.

  4. Add a parameter that is exactly the same as the one you added in Step 2 to the task flow.

24.6.2.2 Creating the Fragments

Create a left fragment for the list of flexfield usages and a right fragment for contexts.

Before you begin: 

Create the page-list task flow and context container task flow as described in Section 24.6.2.1, "Creating the Task Flows".

To create the fragments: 

  1. Create the left and right fragment pages PageListFrag.jsff and ContextPageFrag.jsff.

  2. Add the EffCatPageListContainer seeded task flow from the ViewController Flex-View library to the page list fragment using the parameters listed in Section 24.6.1.1, "Creating a Task Flow for a Single Extensible Flexfield Usage," with the exception that the value for _eff_containerBean should be pageFlowScope.ContainerBean instead of pageFlowScope.EffCategoryPagesBean.

  3. Add the EffContextsPageContainer seeded task flow from the ViewController Flex-View library to the context page fragment using the parameters described in Section 24.6.1.1, "Creating a Task Flow for a Single Extensible Flexfield Usage," with the exception that the value for _eff_containerBean should be pageFlowScope.ContainerBean instead of pageFlowScope.EffCategoryPagesBean.

  4. Drag and drop the page list fragment in the page-list task flow.

  5. Drag and drop the context page fragment in the context task flow.

24.6.2.3 Using the Task Flows in the Page

Use the task flows that you just created in Section 24.6.1.1, "Creating a Task Flow for a Single Extensible Flexfield Usage" to add the usage and context lists to the page.

Before you begin: 

  1. Create the page-list task flow and context container task flow as described in Section 24.6.2.1, "Creating the Task Flows."

  2. Create the left and right fragment pages PageListFrag.jsff and ContextPageFrag.jsff as described in Section 24.6.2.2, "Creating the Fragments."

To use the task flows in the page: 

  1. Open the page and add the splitter.

  2. Add the page list and context page task flows to the left and right facets of the splitter.

  3. Enter the value of pageFlowScope.EffCategoryPagesBean for the ContainerBean parameter to the task flows.

  4. Follow the steps listed in Section 24.6.1.3, "Rendering the Page" to view the user interface.

24.6.3 How to Expose One Logical Page and Its Contexts

You can incorporate an extensible flexfield into an application as a single task flow that presents a set of contexts associated with a specified logical page, which will be identified before the UI page initializes.

To expose one logical page and its contexts, build a UI page that includes a splitter with a single task flow as a dynamic region on the right, and that contains the contexts associated with the selected logical page. This variation does not present an extensible flexfield usage or page-list task flow in the user interface.

24.6.4 How to Expose One Extensible Flexfield Context

Build an application page with a single task flow as a dynamic region on the right, and containing the context that was passed. This variation does not present an extensible flexfield usage or page-list task flow in the user interface.

Before you begin:

Create and configure business components to support the extensible flexfield as described in Section 24.5, "Defining and Registering Extensible Flexfield Business Components."

To expose the extensible flexfield context:

  1. Create a task flow for Pages List, for example, PageListTF.xml.

  2. Add a managed bean, called EffCategoryPagesBean, to this task flow. It should have a class of pageFlowScope.EffCategoryPagesBean and a scope of pageFlow.

  3. Create a fragment, for example PageListFrag.jsff, and drag and drop the EffCatPageListContainer task flow from the ViewController FlexModeler-View library on the fragment.

  4. Add the following parameters:

    • _eff_application_id: Provide #{pageFlowScope._eff_application_id}

    • _eff_descriptive_flexfield_code: Provide #{pageFlowScope._eff_descriptive_flexfield_code}

    • _eff_category_code: Provide #{pageFlowScope._eff_category_code}

    • _eff_usage_code: Provide #{pageFlowScope._eff_usage_code}

    • _eff_page_code: Provide #{pageFlowScope._eff_page_code}

    • _eff_containerBean: Provide #{pageFlowScope.EffCategoryPagesBean}

  5. Place the task flow on any page on which you want the page list to appear.

  6. Create a task flow, for example, ContextsTF.xml.

  7. Add an empty fragment to this task flow, for example, ContextsFrag.jsff.

  8. Access the page on which you would like your contexts to appear. This could possibly be the same page as in Step 5 but is likely the second facet of a splitter.

  9. Drag and drop ContextsTF.xml as a dynamic region onto this page at the correct location.

  10. When prompted for a backing bean, enter a new bean name, class, and package, for example, ContextsRenderingBean.java, and allow it to remain as a backing bean.

  11. Open the Java file and add the following code snippet, replacing the value for taskFlowId with the appropriate string:

    public class ContextsRenderingBean {
      private String taskFlowId = 
    "/WEB-INF/oracle/apps/fnd/applcore/flex/eff/runtime/ui/test/flow/ContextsTF.xml#ContextsTF";
      private String newTaskFlowId =null;
      private boolean refreshRegion = false;
    
      public ContextsRenderingBean () {
      }
    
      public TaskFlowId getDynamicTaskFlowId() {
        return TaskFlowId.parse(taskFlowId);
      }
      public boolean getRefreshRegion() {
        refreshRegion = false;
        newTaskFlowId = (String) ADFContext.getCurrent().getSessionScope().
          get("_eff_context_tf_id");
    
        if (newTaskFlowId != null && taskFlowId.compareTo(newTaskFlowId) != 0 ) {
           taskFlowId = newTaskFlowId;
           refreshRegion = true;
        }
        return refreshRegion;
      }
    }
    
  12. Open the page definition for the launch page and scroll to the location of the dynamic region binding.

  13. Add the following refresh condition setting to the taskFlow tag:

    RefreshCondition="#{backingBeanScope.ContextsRenderingBean.refreshRegion}"
    

    This setting provides the call back and the conditions for the refresh of the contexts region.

  14. Follow the steps listed in Section 24.6.1.3, "Rendering the Page" to view the user interface.

    When you run the page and click on the page link, the call back to refreshRegion will look up the ID for the contexts task flow and enable a refresh of the dynamic region.

24.7 Loading Seed Data

Any implementation of flexfields in Oracle Fusion Applications typically requires application seed data, which is the essential data to enable flexfields to work properly in applications. Flexfield seed data can be uploaded and extracted using Seed Data Loader.

After you complete the registration process described in Section 24.4.1, "How to Register Extensible Flexfields," your flexfield seed data consists of the information that you registered for your flexfield, such as the tables and columns reserved for your flexfield. For a customer flexfield, the seed data contains only this registration data.

If your flexfield is a developer flexfield, you also serve the role of the implementor. In addition to the registration data, your flexfield seed data might include contexts, segments, and value sets that you have defined for your flexfield. You can use the Oracle Fusion Middleware Extensions for Applications (ApplCore) Setup application, as described in Chapter 26, "Deploying Flexfields in a Standalone WebLogic Server Environment," to configure a flexfield. For information how to define contexts, segments, and value sets, see the "Using Flexfields for Custom Attributes" chapter in Oracle Fusion Applications Extensibility Guide.

For information about extracting and loading seed data, see Chapter 56, "Initializing Oracle Fusion Application Data Using the Seed Data Loader.".

24.8 Customizing the Extensible Flexfield Modelers

You can customize the modelers that generate the extensible flexfield business component and UI artifacts to add additional product-specific logic. For example, you might want the modeler to set a specific JavaServer Pages (JSP) Expression Language (EL) expression on a generated segment's ReadOnly property.

24.8.1 How to Customize the Runtime Business Component Modeler for Extensible Flexfields

To extend the extensible flexfield runtime business component modeler, override the EFFBCModelerFactory.getCustomEFFBCModeler method, shown in Example 24-3, in the custom extensible flexfield runtime business component modeler factory.

Example 24-3 getCustomEFFBCModeler Method

/**
   * Implementing teams need to override this method and provide the
   * custom BC Modeler here (e.g. PIMBCModeler).
   * @param namespace the name space
   * @param flexDef the flexfield def
   * @param entityUsage the entity usage
   * @param writer the modeler writer
   * @param conf the configuration
   * @param categoryDef the category def
   * @param categoryContextDef the category context def
   * @param categoryCode the category code
   * @param contextCode the context code
   * @param appShortName the application short name
   * @param flexCode the flexfield code
   * @param connUrl the connection url
   * @param isInterface the interface flag
   * @return the custom EFF BC Modeler instance.
   */
  protected EFFBCModeler getCustomEFFBCModeler(FlexfieldNamespace namespace,
                                            FlexfieldDef flexDef,
                                            FlexfieldEntityUsage entityUsage,
                                            BCModelerWriter writer,
                                            Map<BCModeler.Option, Object> conf,
                                            CategoryDef categoryDef,
                                            CategoryContextDef categoryContextDef,
                                            String categoryCode,
                                            String contextCode,
                                            String appShortName,
                                            String flexCode,
                                            String connUrl,
                                            boolean isInterface)
  {
    return new EFFBCModeler(namespace, flexDef, entityUsage, writer, conf,
                            categoryDef, categoryContextDef, categoryCode,
                            contextCode, appShortName, flexCode, connUrl,
                            isInterface);
  }

An example of the PIMBCModelerFactory.java override for this method is shown in Example 24-4.

Example 24-4 PIMBCModelerFactory.java Override

protected EFFBCModeler getCustomEFFBCModeler(FlexfieldNamespace namespace,
                                            FlexfieldDef flexDef,
                                            FlexfieldEntityUsage entityUsage,
                                            BCModelerWriter writer,
                                            Map<BCModeler.Option, Object> conf,
                                            CategoryDef categoryDef,
                                            CategoryContextDef categoryContextDef,
                                            String categoryCode,
                                            String contextCode,
                                            String appShortName,
                                            String flexCode,
                                            String connUrl,
                                            boolean isInterface)
  {
    return new PIMBCModeler(namespace, flexDef, entityUsage, writer, conf,
                            categoryDef, categoryContextDef, categoryCode,
                            contextCode, appShortName, flexCode, connUrl,
                            isInterface);
  }

24.8.2 How to Customize the Runtime User Interface Modeler for Extensible Flexfields

If the UI artifacts that are generated for an extensible flexfield business component do not fulfill application requirements, you can create wrapper implementation classes for the framework's customizer interfaces. These wrapper implementation classes enable some control over the XML that the modeler generates for the UI artifacts just before it persists the generated task flows and JavaServer Faces (JSF) page fragments. The implementation classes are in the oracle.apps.fnd.applcore.flex.uimodeler.customizers package.

To customize an extensible flexfield business component's generated UI artifacts:

  1. Create wrapper classes for the default customizer implementation classes.

  2. Create a wrapper of the metadata provider implementation class.

  3. Register the metadata provider wrapper class in the metadata for the flexfield's business component.

24.8.2.1 Creating the Customizer Wrapper Class

Extend the default customizer implementation classes from the oracle.apps.fnd.applcore.flex.uimodeler.customizers package to customize the following UI artifacts:

  • Context JSF fragment

  • Segment components in the generated context task flow

  • Page links in the generated links task flow

  • Page task flow

  • Search task flow

24.8.2.1.1 How to Customize the Context JSF Page Fragment

To customize the JSF page fragment for a single row context, create a wrapper class for the SingleRowContextRegionCustomizerImpl implementation class and override the customizeGeneratedSingleRowContextFragment method.

To customize the JSF page fragment for a multiple row context, create a wrapper class for the MultiRowContextRegionCustomizerImpl implementation class and override the customizeGeneratedMultiRowContextFragment method.

24.8.2.1.2 How to Customize the Segment Components in the Generated Context Task Flow

To customize which segment components in the generated context task flow are read-only for single and multi-row contexts, create a wrapper class for the ContextComponentsCustomizerImpl implementation class and override the getAtributeComponentReadonlyELExpression method. This method returns the value of the readOnly property for a given segment component in the context task flow, as shown in Example 24-5.

Example 24-5 Sample getAtributeComponentReadonlyELExpression Method

public String getAtributeComponentReadonlyELExpression(
  Transaction tx, ViewDef contextViewDef) {
        String returnData = null;
        ViewDefImpl contextViewDefImpl = (ViewDefImpl) contextViewDef;
 
        if(contextViewDefImpl.getName().toUpperCase().indexOf("RESOLUTION") >0 ) {
             returnData = "#{pageFlowScope.EFF_PARAM5=='Y'}";
        }
         return returnData;
    }
24.8.2.1.3 How to Customize the Page Links in the Generated Links Task Flow

To customize which page links in a generated links task flow are rendered, create a wrapper class for the PageListCustomizerImpl implementation class and override the getPageLinkRenderedProperty method. This method returns the value of the rendered property for a page link.

24.8.2.1.4 How to Customize the Page Task Flow

To customize which context task flows are rendered in a page task flow, create a wrapper class for the ContainerPageCustomizerImpl implementation class and override the getContextTFRenderedELExpression method. This method returns the value of the region tag for a context task flow.

24.8.2.1.5 How to Customize the Search Task Flow

To customize the search task flow, create a wrapper class for the SearchRegionCustomizerImpl implementation class. Example 24-5 shows the ways in which you can customize the search task flow and the methods to override to perform the customizations.

Table 24-4 Methods to Override to Customize the Search Task Flow

Customization Method to Override Notes

Set the list of actions required in the search results table.

getResultTableActionMenu

Use the ResultsTableActionMenu inner class to define the menu properties and entries.

Set the managed bean for the generated task flow.

getSearchManagedBeanClass

The manage bean must extend oracle.apps.fnd.applcore.flex.eff.search.ui.bean.DefaultEffSearchManagedBean.

Alter properties in the product table component for search results.

getApplicationsTablePropertiesMap

This method returns a hashmap of name-value pairs of the properties to be set.

Alter properties in the ADF Table that is in the product table component for search results.

getADFTablePropertiesMap

This method returns a hashmap of name-value pairs of the properties to be set, as shown in Example 24-6.

Customize the query panel properties.

getQueryPanelPropertiesMap

This method returns a hashmap of name-value pairs of the properties.

Get a handle to the document object model (DOM) object of the generated search region and its pageDef.

customizeGeneratedSearchTaskflowRegion

Use DOM objects to customize generated artifacts only if there is no other way to perform for the customization.

Customize the readOnly property for a component in search results table column.

getResultsTableColumnComponentReadOnlyELExpression

This method returns a JSP EL expression.

Customize the properties on the search results table column for an attributeDef.

getResultsTableColumnPropertiesMap

This method returns a hashmap of name-value pairs of the properties.

Set the task flow data control scope to shared.

getSearchTaskFlowDataControlScope

The task flow can be generated with either a SHARED scope or a ISOLATED scope. The default is ISOLATED. Override this method to set the scope to SHARED.

Add custom toolbar components.

getAdditionalToolbarComponentDefinitions

Use the AdditionalToolbarComponentDefinition inner class to provide metadata for the required component. You can add components of type CHOICELIST, BUTTON, SPACER, and SEPARATOR.

Set the default search criteria on the search page as it is loaded.

getDefaultSearchCriteriaName

 

Customize the generated search task flow XML.

customizeGeneratedSearchTaskflow

This method returns a handle to the DOM object for the generated task flow XML. You only should use DOM objects to customize generated artifacts if there is no other way to perform the customization.


Example 24-6 Sample getADFTablePropertiesMap Method

public HashMap getADFTablePropertiesMap()
    {
        HashMap propertiesMap = new HashMap(10);
        propertiesMap.put("filterVisible","false");
        propertiesMap.put("columnStretching","column:description");
        propertiesMap.put("inlineStyle","width:100%;");
        return propertiesMap;
    }
24.8.2.1.6 How to Create a Metadata Provider Implementation

If you have created customizer wrapper classes for a flexfield business component, you must create a wrapper of the default UIModelerMetadataProviderImpl implementation for that business component. This class is in the oracle.apps.fnd.applcore.flex.uimodeler package.

Override the appropriate methods in the following list to return the names of the custom wrapper classes. For example, if you created a custom wrapper class to customize the search task flow, you would override the getSearchRegionCustomizerClassName method, as shown in Example 24-7. Override only the methods that correspond to the classes for which you have created custom wrappers. In the case of a SearchRegionCustomizerImpl custom wrapper, the method that you override depends on whether the wrapper customizes the interface search UI or the regular search UI. If the wrapper customizes the interface search UI, override the getInterfaceSearchRegionCustomizer method. Otherwise, override the getSearchRegionCustomizerClassName.

  • getContextComponentCustomizerClassName

  • getContainerPageCustomizerClassName

  • getPageListCustomizerClassName

  • getSearchRegionCustomizerClassName

  • getInterfaceSearchRegionCustomizer

  • getSingleRowContextRegionCustomizerClassName

  • getMultiRowContextRegionCustomizerClassName

Example 24-7 Sample getSearchRegionCustomizerClassName Method

public String getSearchRegionCustomizerClassName() {
        return "oracle.apps.myProduct.myApp.items.eff.ItemSearchRegionCustomizer";
    }
24.8.2.1.7 How to Register the Metadata Provider Class for the Business Component

In order for the user interface modeler to use your custom wrapper classes at runtime, you must register the metadata provider class. To register the class, set the ADFUI_MODELER column for the business component's row in the FND_DF_FLEXFIELDS_B table to the name of the UIMetadataProviderImpl implementation class that you created for the business component.

24.9 Testing the Flexfield

After implementing a flexfield, you can define seed or test value sets for the flexfield, and you can create a model that you can use to test it. For more information, see Section 26.1.2, "How to Test Flexfields".

24.10 Accessing Information About Extensible Flexfield Business Components

The consumers of an extensible flexfield might need to programmatically access an extensible flexfield, such as to further process the data that has been entered for an extensible flexfield, to add additional validation, or to perform change control. The oracle.apps.fnd.applcore.flex.runtime.util.common.ExtensibleFlexfieldUtil package provides methods for obtaining the handles to the artifacts that are generated in a customer's instance.

24.10.1 How to Access Information About Extensible Flexfield Business Components

Use the methods in oracle.apps.fnd.applcore.flex.runtime.util.common.ExtensibleFlexfieldUtil to get the names of the following generated extensible flexfield Java business objects (JBOs):

  • Context entity object: Use getContextEoName, which is shown in Example 24-8.

  • Context view object: Use getContextVoName, which is shown in Example 24-9.

  • Context entity association between base and extension entity objects: Use getCategoryContextAssocName, which is shown in Example 24-10.

  • Context entity/view object attribute for a given segment code: Use getContextAttributeName, which is shown in Example 24-11.

  • Categories: Use the various methods shown in Example 24-12.

  • Search view object attributes: Use getSearchVoAttributeNames, which is shown in Example 24-13.

Example 24-8 Method to Get EFF Context Entity Object Name

/**
   * @param appId - application id
   * @param flexCode - flexfield code (e.g. EGO_ITEM_UDA)
   * @param flexUsageCode - flexfield usage code (e.g. EGO_ITEM_DL)
   * @param txn - DB transaction
   * @param contextCode - context code (e.g Voltage)
   * @param tableType - table type (e.g. EXTENSION)
   * @param effGroup - eff grouping entity name (public / private)
   * @return
   */
  public static String getContextEoName(Long appId, String flexCode,
                                        String flexUsageCode,
                                        DBTransaction txn,
                                        String contextCode,
                                        String tableType,
                                        String effGroup)

Example 24-9 Method to Get EFF Context View Object Name

/**
   * @param appId - application id
   * @param flexCode - flexfield code (e.g. EGO_ITEM_UDA)
   * @param flexUsageCode - flexfield usage code (e.g. EGO_ITEM_DL)
   * @param txn - DB transaction
   * @param contextCode - context code (e.g Voltage)
   * @param tableType - table type (e.g. EXTENSION)
   * @param effGroup - eff grouping entity name (public / private)
   * @return
   */
  public static String getContextVoName(Long appId, String flexCode,
                                        String flexUsageCode,
                                        DBTransaction txn,
                                        String contextCode,
                                        String tableType,
                                        String effGroup)

Example 24-10 Method to Get Name for EFF Context Entity Association Between Base and Extension Entity Objects

/**
   * @param appId - application id
   * @param flexCode - flexfield code (e.g. EGO_ITEM_UDA)
   * @param flexUsageCode - flexfield usage code (e.g. EGO_ITEM_DL)
   * @param txn - DB transaction
   * @param contextCode - context code (e.g Voltage)
   * @param tableType - table type (e.g. EXTENSION)
   * @param effGroup - eff grouping entity name (public / private)
   * @return
   */
  public static String getCategoryContextAssocName(Long appId, String flexCode,
                                                   String flexUsageCode,
                                                   DBTransaction txn,
                                                   String contextCode,
                                                   String tableType,
                                                   String effGroup)

Example 24-11 Method to Get Attribute Name for EFF Context Entity/View Object Given Segment Code (FND_DF_SEGMENTS_VL.SEGMENT_CODE)

/**
   * Get the attribute name for the EFF context view
   * object / entity object given the segment code.
   * @param segmentCode - segment code for attribute name.
   * @return attribute name
   */
  public static String getContextAttributeName(String segmentCode)

Example 24-12 EFF Category Methods

public static String getCategoryAmNameForWebServices()
public static String getCategoryAmNameForDataEntry()
public static String getCategoryAmNameForInterfaceGeneric()
public static String getCategoryAmNameForInterfaceCategory()
public static String getCategoryAmNameForSearchGeneric()
public static String getCategoryAmNameForSearchCategory()
public static String getCategoryVoNameForDataEntry()
public static String getCategoryVoNameForWebServices()
public static String getCategoryVoNameForInterfaceGeneric()
public static String getCategoryVoNameForInterfaceCategory()
public static String getCategoryContextViewLinkNameForInterfaceGeneric()
public static String getCategoryContextViewLinkNameForInterfaceCategory()
public static String getCategoryContextViewLinkNameForSearchCategory()
public static String getCategoryContextViewLinkNameForSearchGeneric()
public static String getCategoryContextViewLinkNameForWebService()
public static String getCategoryContextViewLinkNameForDataEntry()
public static void useServiceProvider()
public static String getCategoryVoNameForSearchCategory()
public static String getCategoryVoNameForSearchGeneric()

Example 24-13 Method to Get Hash Map of View Object Attribute Names for EFF Search View Object

/**
   * Get a map of segment codes to search view object attribute names
   * @param flexUsageCode - flexfield usage code (e.g. EGO_ITEM_DL)
   * @param contextCode - context code (e.g Voltage)
   * @param segmentCodeList - segment codes for the map.
   * @return map of attribute names with key of segment codes
   */
  public static HashMap<String, String> getSearchVoAttributeNames( 
                                               String flexUsageCode,
                                               String contextCode,
                                               ArrayList<String> segmentCodeList)