How To Use Descriptive Flexfield In Oracle Apps

34/82

23 Use Descriptive Flexfields

23.1 Introduction to Descriptive Flexfields

Descriptive flexfields provide a way for implementors at customer sites to add custom attributes to entities, and to define validation and display properties for them. A descriptive flexfield is a logical grouping of segments that is mapped to a set of database columns that serve as placeholders for custom attributes. These placeholder columns are often referred to as extension columns. The attributes in the group are of three types: global segment, context-sensitive segment, and context segment. The global segments are for custom attributes that apply to all entity rows, while the context-sensitive segments are for custom attributes that apply to certain entity rows based on the value of a context segment.

As the developer, you can define multiple usages for a descriptive flexfield. For example, you might have defined an address flexfield that the implementor may use to add attributes related to addresses. The implementor can define context-sensitive segments for the address that are based on a certain attribute, such as country code. You can reuse the address flexfield with any table for which you need address information, and the implementor needs to configure the flexfield only once.

To complete the development tasks for descriptive flexfields:

1. Create the extension columns to store the flexfield data, and then register the flexfield definition, usage, and parameter metadata.

2. Create descriptive flexfield business components.

   Tip:

   After completing this step, you can regenerate the flexfield business components programmatically at runtime to update your descriptive flexfield implementation without manual intervention.

3. Create view links between the descriptive flexfield business components and the application's business components.

4. Nest the descriptive flexfield application module instance in the application module.

5. Add an instance of the descriptive flexfield view object to the application module.

6. Add the descriptive flexfield usage to the appropriate application pages.

7. Configure the descriptive flexfield UI components.

8. Test the flexfield.

9. Load any necessary application seed data, such as error messages or lookup values.

After implementing a flexfield, you can define seed or test configurations for the flexfield, and then test it.

After you have completed the flexfield development process and delivered your application, implementors can use the Manage Descriptive Flexfields task flows to define context values and to configure the segments for each flexfield. These task flows determine how the flexfield's segments will be populated, organized, and made available to end users within the application.

To make the Manage Descriptive Flexfields task flows available to implementors, register them with the Oracle Fusion Functional Setup Manager.

The following links provide more information within this book:

• For more information about flexfield basics and terms, including developer and implementor roles, global segments, context-sensitive segments, and context segments, see Getting Started with Flexfields.

• For more information about developer and implementor roles, see Participant Roles.

• For more information about storing and registering descriptive flexfield data, see Developing Descriptive Flexfields.

• For more information about creating descriptive flexfield business components, see Creating Descriptive Flexfield Business Components.

• For more information about regenerating flexfield business components, see Regenerating Flexfield Business Components Programmatically.

• For more information about creating view links between descriptive flexfield business components, see Creating Descriptive Flexfield View Links.

• For more information about nesting descriptive flexfield application module instances in an application module, see Nesting the Descriptive Flexfield Application Module Instance in the Application Module.

• For more information about adding descriptive flexfield view objects to an application module, see Adding a Descriptive Flexfield View Object to the Application Module.

• For more information about adding descriptive flexfield components to application pages, see Adding Descriptive Flexfield UI Components to a Page.

• For more information about configuring descriptive flexfield UI components, see Configuring Descriptive Flexfield UI Components.

• For more information about testing flexfields, see Testing Flexfields.

• For more information about loading application seed data, see Loading Seed Data.

• For more information about testing and deploying flexfields, see Introduction to Testing and Deploying Flexfields.

• For more information about registering descriptive flexfield task flows, see Integrating Flexfield Task Flows into .

Related Links

The following documents provide additional information related to subjects discussed in this section:

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.

23.1.1 Benefits of Descriptive Flexfields

Descriptive flexfields let you satisfy different customers without having to reprogram the application, by enabling the customers to add customized fields. Descriptive flexfields also enable context-sensitive fields that appear only when needed. In essence, a descriptive flexfield enables implementors to extend the data model without writing either XML or Java. A descriptive flexfield is presented as a set of fields on a page, much like the fields of the core application.

For example, consider a retail application that keeps track of customers. The customer form would typically include fields such as Name, Address, State, Customer Number, and so on. However, the page might not include fields to keep track of customer clothing size and color preferences, because these are attributes that can differ for each company that uses the application. For example, if the retail application is used for a tool company, a field for clothing size would be undesirable. Even if you initially provide all the fields that a company needs, the company might later identify even more customer attributes that it wants to track. You can add a descriptive flexfield to the customer form to provide the desired expansion space. Companies also can take advantage of the fact that descriptive flexfields can be context-sensitive, where the information that the application stores depends on other values that the end users enter on other parts of the page. For example, a company could configure the descriptive flexfield for a fixed asset form to store style, size, and wood type if the asset type was "desk", and store CPU chip and memory size if the asset type was "computer."

Another example is the descriptive flexfield in the Oracle General Ledger journal entry form. Implementors can configure the flexfield to add information of a customer's own choosing. For example, a customer might want to capture additional information about each journal entry, such as source document number, or the name of the person who prepared the entry.

To maximize flexibility for customers, consider defining a descriptive flexfield for every entity in your application to which a customer might need to add attributes.

23.1.2 How Descriptive Flexfields Are Modeled in Oracle Application Development Framework

Flexfields are modeled as a collection of Oracle Application Development Framework (Oracle ADF) polymorphic view rows, as described in the Working with Polymorphic View Rows section in the Developing Fusion Web Applications with Oracle Application Development Framework . In a polymorphic collection of rows, each view row can have its own set of attributes, and all rows have at least one common attribute, the discriminator. The discriminator determines which view row type is used. Given a collection of polymorphic view rows, each row can be a different type.

The attribute sets that are associated with the discriminator are predefined. In fact, Oracle ADF enables each view row to have its own view definition. When a polymorphic collection of rows is created, Oracle ADF selects a view definition for the row to be added based on the value of the discriminator attribute.

Descriptive flexfield segments are exposed as view row attributes in the order that they are defined in the flexfield's metadata. Global segments are exposed as attributes in the base view object of the polymorphic collection. Every context is modeled as an extended view object of the base view object. That is, an extended view object is created for every context value. These extended view objects, which are referred to as subtype view objects, expose context-sensitive segments as subtype-specific view attributes. The context segment is exposed as the discriminator attribute of the polymorphic view rows.

You use a wizard to generate a polymorphic base view object that is based on the descriptive flexfield definition, then create a view link to connect the product view object and the base view object. You can then use the base view object to add the flexfield to a UI page. For more information about the generation of base and subtype view objects, see Creating Descriptive Flexfield Business Components.

Note:

One distinction of the flexfield context-switching mechanism is that during context switching, the context-sensitive segments are initialized as follows:

• If a segment is defined to use a constant value from an underlying entity object as its default, it is initialized to that value.

• If a segment is defined to use a descriptive flexfield parameter by default, it is initialized to that value.

• For all other cases, the context-sensitive segment is set to NULL.

For more information about polymorphic view rows, see the Working with Polymorphic View Rows section in the Developing Fusion Web Applications with Oracle Application Development Framework .

Note:

Because flexfield view objects are modeled as polymorphic view objects, you can use descriptive flexfield view objects in the same manner that you use any other polymorphic view objects, and they will behave in the same way. This includes support for flexfields in ADF Desktop Integration. For more information, see Accessing Descriptive Flexfields from an ADF Desktop Integration Excel Workbook and the Oracle Fusion Middleware Developing Applications with Oracle ADF Desktop Integration guide.

23.2 Develop Descriptive Flexfields

Whenever you have a product table that you think implementors might need to extend for their specific circumstances, you can add columns to the table and register those columns as flexfield segments. After you have registered a flexfield, you can reuse the flexfield with other product tables.

To complete the process for developing a descriptive flexfield:

1. Add extension columns to the product table.

2. Register the flexfield and define its metadata and primary usage.

3. Register the entity details and parameters for the primary usage.

4. Optionally reuse the flexfield by adding the same set of extension columns to other product tables.

5. Register the secondary usages and their entity details.

23.2.1 How to Create Descriptive Flexfield Columns

To implement a descriptive flexfield for a product table, you first add extension columns to that table. You need to add a context column, such as ATTRIBUTE_CATEGORY, and as many generic attribute (segment) columns of each type, such as ATTRIBUTE_CHAR1 and ATTRIBUTE_NUMBER12, as will be needed by the implementors. A segment column must be a VARCHAR2, NUMBER, DATE, or TIMESTAMP. When using a flexfield to add a custom attribute, the implementor maps the custom attribute to an available extension column.

Tip:

There are no constraints on how to name the segment columns. However, these columns are typically named using the patterns ATTRIBUTE_CHARn, ATTRIBUTE_NUMBERn, ATTRIBUTE_DATEn, and ATTRIBUTE_TIMESTAMPn. This convention makes it easy to identify the flexfield segments. It also makes it easier to name the columns for other usages of the flexfield.

The context column, which is required, must be of type VARCHAR2. The context column's length determines the maximum length of the context codes that can be created by implementors when they configure the flexfields.

Each implementor can configure as many of the segment columns as the end user requires and can choose whether to use the context column.

You must use the Database Schema Deployment Framework tools to create the product table 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 Using the Database Schema Deployment Framework.

23.2.2 How to Register and Define Descriptive Flexfields

Before you can create business components for a descriptive flexfield, you must first define and register the descriptive flexfield.

The basic steps for defining and registering a descriptive flexfield are as follows:

• Name and describe the flexfield.

• Indicate whether the flexfield should be protected from end-user configuration. If a flexfield is protected, it cannot be edited using setup tasks, such as Manage Descriptive Flexfields. Typically, this option is used for developer flexfields. Note that you must use the APIs to do this step. For information, see Using the Setup APIs To Register and Define Descriptive Flexfields.

• Define the primary usage. The primary usage is the first usage that you define for a flexfield.

• Define the product table column to be used for the context segment. The product table that is used for the primary usage is called the primary table.

• Define the product table columns to be used for the flexfield segments.

There are two ways in which you can define a descriptive flexfield:

• Using the Flexfield Registration Metadata wizard. If you use the wizard, you also define the entity details for the primary usage and you define the parameters.

• Using the setup APIs in the FND_FLEX_DF_SETUP_APIS PL/SQL package.

23.2.2.1 Using the Flexfield Registration Metadata Wizard To Register and Define Descriptive Flexfields

You can use the Register new flexfield operation from the Flexfield Registration Metadata wizard to register and define a descriptive flexfield.

Tip:

To make subsequent flexfield additions and changes, you can use the Edit flexfield operation from the Flexfield Registration Metadata wizard.

Before you begin:

• Create the extension columns as described in How to Create Descriptive Flexfield Columns.

• Ensure that entity objects exist for the primary table.

To register and define a descriptive flexfield using the Flexfield Registration Metadata wizard:

1. From the File menu, choose New.
2. In the New Gallery, expand Business Tier, select ADF Business Components and then Flexfield Registration Metadata, and click OK.
3. On the Choose Operation page of the Flexfield Registration Metadata wizard, select Register new flexfield as shown in Figure 23-1, and then click Next.

   Figure 23-1 Flexfield Registration Metadata Wizard — Choose Operation Page

   

4. On the Basic Information page, select Descriptive Flexfield from the Type dropdown list, as shown in Figure 23-2.

   Figure 23-2 Flexfield Registration Metadata Wizard — Basic Information Page

   

5. Provide the following values:

   • Code: Type a code that uniquely identifies the flexfield.

   • Name: Type a descriptive name for the flexfield.

   • Description: Type a short description of the flexfield.

   • Application: Select the application name that has been assigned for the product area.

   • Module: Select the module that owns the flexfield. This is typically the application or logical business area (LBA) with which the flexfield is delivered.

   • Delimiter: Select the character to be displayed between flexfield segments, when the segments are displayed in a concatenated format.

   • Enable Business Intelligence: (Optionally) Select the checkbox to enable the flexfield for Oracle Business Intelligence. For more information, see Preparing Descriptive Flexfield Business Components for .

6. Click Next.
7. On the Primary Table page, set the following values to define the primary usage for the flexfield, as shown in Figure 23-3.

   • Base Table: Enter or select the name of the database table that contains the columns to be used as flexfield segments.

   • Table Usage Code: Type a code that uniquely identifies the flexfield usage. For the primary usage, this is typically the same code as the flexfield code.

   • Table Usage Name: Type a descriptive name for the flexfield usage.

   Figure 23-3 Flexfield Registration Metadata Wizard — Primary Table Page

   

8. From the Context Column dropdown list, select the database column that you want to map to the flexfield's context segment. The column must be of type VARCHAR2.

   Tip:

   The context segment database column is typically named ATTRIBUTE_CATEGORY.

9. In the Available list in the Segment Columns region, select the database columns that you want to map to flexfield segments and move them to the Selected list.
10. Click Next.
11. On the Entities page, select the entity objects for the table upon which the usage is based and move them to the Selected list, as shown in Figure 23-4.

    Figure 23-4 Flexfield Registration Metadata Wizard — Entities Page

    

12. Select each entity object from the Selected list and provide the following values:

    • Object Name Prefix: Enter a short unique name for the flexfield usage. For example, PartsDFF. This prefix is used to derive the names of objects that are generated for the flexfield usage.

    • Package Name: Specify the name of the root package to be used for the generated business components that model the flexfield usage.

    • BI Flattened Fact Name: If the flexfield is enabled for Oracle Business Intelligence and you know the Oracle Business Intelligence object that this flexfield usage should be mapped to when the flexfield is imported into Oracle Business Intelligence, specify the name of the object.

      For more information about Oracle Business Intelligence, see Preparing Descriptive Flexfield Business Components for .

13. Click Next.
14. On the Parameters Page, optionally define parameters for the entity object attributes that can be used to pass external reference data to flexfield segments, as shown in Figure 23-5.

    Figure 23-5 Flexfield Registration Metadata Wizard — Parameters Page

    

15. On the Summary page, optionally select Extract seed data for the flexfield to create a seed data file for uploading the registration information into other implementations. For more information, see Loading Seed Data.
16. If you are ready to create business components for the flexfield, select Launch Flexfield Business Components Wizard.
17. Click Finish.

23.2.2.2 Using the Setup APIs To Register and Define Descriptive Flexfields

To register and define a descriptive flexfield using the setup APIs:

1. Run the fnd_flex_df_setup_apis.create_flexfield(...) procedure to register the descriptive flexfield, its context segment, and its primary (master) usage. If you do not want end users to configure the flexfield, set the protected flag to N.
2. Run the fnd_flex_df_setup_apis.create_segment_column_usage(...) procedure for each segment column to register the segment columns.
3. (Optionally) Register the entity details as described in How to Register Entity Details. This step must be completed before you can generate the flexfield usage's business components.

23.2.2.2.1 What You May Need to Know About the Descriptive Flexfield Setup API

In the descriptive flexfield development process, use the FND_FLEX_DF_SETUP_APIS PL/SQL package to manage flexfield registration metadata.

You can learn about the FND_FLEX_DF_SETUP_APIS PL/SQL package by running the following command, which stores package documentation and usage examples in the <db_name>_<user_name>_FND_FLEX_DF_SETUP_APIS_<date>.plsqldoc file.

sqlplus <fusion_user>/<fusion_pwd>@<fusion_db> \ @/ORACLE/fusionapps/atgpf/applcore/db/sql/flex/fnd_flex_pkg_doc.sql \  FND_FLEX_DF_SETUP_APIS                  

23.2.3 How to Reuse a Descriptive Flexfield on Another Table

A descriptive flexfield configuration can be shared with other product tables. To reuse a descriptive flexfield, you add the same set of extension columns to the product table for which you want to reuse the flexfield, and you register the secondary usage as described in How to Register the Reuse of a Descriptive Flexfield.

The product table that was used to register the flexfield is referred to as the primary table, and it is the owner of the flexfield. The usage that you create when you register the flexfield is called the primary usage. A reuse of a flexfield is referred to as a secondary usage.

The secondary table must have the same number of extension columns as the primary table. The secondary extension columns must have the same data type and size as the corresponding primary table extension columns.

The column names must also be the same as in the primary table, except for an optional prefix. For example, if the column names are ATTRIBUTE1 and ATTRIBUTE2 in the primary table, then in the secondary table they could again be ATTRIBUTE1 and ATTRIBUTE2, respectively, or with a prefix, they could be HOME_ATTRIBUTE1 and HOME_ATTRIBUTE2. They cannot be ATTR1, HOME_ATTR2, or any variation that does not end in the names of the primary table columns.

When configuring the flexfield, the implementor can configure as many of the segment columns as the end user requires and can choose whether to use the context column.

You must use the Database Schema Deployment Framework tools to create the product table 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 Using the Database Schema Deployment Framework.

23.2.4 How to Register the Reuse of a Descriptive Flexfield

After you add extension columns to a table for a secondary usage of a flexfield, you must register the usage before you can build a descriptive business component for the secondary usage.

There are two ways in which you can register a secondary usage:

• Using the Flexfield Registration Metadata wizard. If you use the wizard, you also define the entity details for the secondary usage.

• Using the setup APIs in the FND_FLEX_DF_SETUP_APIS PL/SQL package.

23.2.4.1 Using the Flexfield Registration Metadata Wizard To Register a Secondary Usage

You can use the Register new flexfield usage operation from the Flexfield Registration Metadata wizard to register the secondary usage of a descriptive flexfield. The registration wizard uses the primary usage column mappings to determine how to map the secondary table's column names to the flexfield segments. If you specify a prefix, the wizard uses the prefix to determine the column mappings. For example, if the primary table's ATTRIBUTE1 column is mapped to a segment, and you specify a prefix of HOME for the secondary usage, the wizard automatically maps its HOME_ATTRIBUTE1 column to a flexfield segment.

Before you begin:

1. Register the descriptive flexfield and its primary usage as described in How to Register and Define Descriptive Flexfields.

2. Create the extension columns for the secondary usage as described in How to Reuse a Descriptive Flexfield on Another Table.

3. Ensure that entity objects exist for the secondary table.

To register a second usage using the Flexfield Registration Metadata wizard:

1. From the File menu, choose New.
2. In the New Gallery, expand Business Tier, select ADF Business Components and then Flexfield Business Components, and click OK.
3. On the Choose Operation page of the Flexfield Registration Metadata wizard, select Register new flexfield usage, and then click Next.
4. On the Select Usage page, select Descriptive from the Type dropdown list, as shown in Figure 23-6.

   Figure 23-6 Flexfield Registration Metadata Wizard — Select Usage Page

   

5. To display available usages, provide a value for Application, Code, or Table. You can use a wildcard character, such as a percent sign (%), to match on similar values.
6. Select the primary usage of the flexfield for which you want to create the secondary usage, and then click Next.
7. On the Basic Information page, review the information about the primary usage, and then click Next.
8. On the Secondary Table page, set the following values to define the secondary usage for the flexfield, as shown in Figure 23-7.

   • Base Table: Enter or select the name of the secondary table.

   • Table Usage Code: Type a code that uniquely identifies the secondary usage.

   • Table Usage Name: Type a descriptive name for the flexfield usage.

   • Column Name Prefix: If you used a prefix for the flexfield column names, enter the prefix.

   Figure 23-7 Flexfield Registration Metadata Wizard — Secondary Table Page

   

9. Click Next.
10. On the Entities page, select the entity objects for the secondary table and move them to the Selected list.
11. Select each entity object from the Selected list and provide the following values:

    • Object Name Prefix: Enter a short unique name for the secondary usage. For example PartsDFFIntf. This prefix is used to derive the names of objects that are generated for the flexfield usage.

    • Package Name: Specify the name of the root package to be used for the generated business components that model the secondary usage.

      Note:

      Each usage must have a unique package name. In addition, the package name must uniquely identify a usage. For example, if the root package for a usage is oracle.apps.flex.hcm.payroll.dff1, then you cannot define the oracle.apps.flex.hcm.payroll package for another usage, because that package would then identify both usages. Instead, you could use oracle.apps.flex.hcm.payroll.dff2.

    • BI Flattened Fact Name: If the flexfield is enabled for Oracle Business Intelligence and you know the Oracle Business Intelligence object that this usage should be mapped to when the flexfield is imported into Oracle Business Intelligence, specify the name of the object.

      For more information about Oracle Business Intelligence, see Preparing Descriptive Flexfield Business Components for .

12. Click Next.
13. On the Summary page, optionally select Extract seed data for the flexfield to create a seed data file for uploading the registration information into other implementations. For more information, see Loading Seed Data.
14. If you are ready to create business components for the flexfield, select Launch Flexfield Business Components Wizard.
15. Click Finish.

23.2.4.2 Using the Setup APIs To Register a Secondary Usage

You can define and register the secondary usage of a descriptive flexfield using procedures from the FND_FLEX_DF_SETUP_APIS PL/SQL package.

To learn how to generate documentation about using the FND_FLEX_DF_SETUP_APIS PL/SQL package, see What You May Need to Know About the Descriptive Flexfield Setup API.

The definition of a descriptive flexfield usage includes the following information:

To register a secondary usage using the setup APIs:

1. To register the secondary usage of a descriptive flexfield, run the fnd_flex_df_setup_apis.create_flex_table_usage(...)procedure.
2. (Optionally) Register the entity details as described in How to Register Entity Details. This step must be completed before you can generate the flexfield usage's business components.

23.2.5 How to Register Entity Details

Before you can create a flexfield business component and create flexfield-specific application module instances, you must register the following information:

• The full class name of the entity object for the table upon which the flexfield usage is based.

• A prefix from which to derive the names of generated objects.

• The package in which to place the generated business components. Each usage must have its own package name.

  Note:

  Each usage must have a unique package name. In addition, the package name must uniquely identify a usage. For example, if the root package for a usage is oracle.apps.flex.hcm.payroll.dff1, then you cannot define the oracle.apps.flex.hcm.payroll package for another usage, because that package would then identify both usages. Instead, you could use oracle.apps.flex.hcm.payroll.dff2.

If you used the Flexfield Registration Metadata wizard to define the flexfield usage, then you have already registered the entity details. Otherwise, you can use the Flexfield Registration Metadata wizard or the FND_FLEX_DF_SETUP_APIS PL/SQL package to register this information for a flexfield usage.

23.2.5.1 Using the Flexfield Registration Metadata Wizard to Register Entity Details

You can use the Edit flexfield usage operation from the Flexfield Registration Metadata Wizard to register entity details.

To register a usage using the Flexfield Registration Metadata wizard:

1. From the File menu, choose New.
2. In the New Gallery, expand Business Tier, select ADF Business Components and then Flexfield Business Components, and click OK.
3. On the Choose Operation page of the Flexfield Registration Metadata wizard, select Edit Flexfield Usage, and then click Next.
4. To display available usages, provide a value for Application, Code, or Table. You can use a wildcard character, such as a percent sign (%), to match on similar values.
5. Select the flexfield usage for which you want to add entity details.
6. Click Next until you are on the Entities page.
7. On the Entities page, select the entity objects for the table upon which the usage is based and move them to the Selected list.
8. Select each newly added entity object from the Selected list and provide the following values:

   • Object Name Prefix: Enter a short unique name for the flexfield usage. For example PartsDFF. This prefix is used to derive the names of objects that are generated for the flexfield usage.

   • Package Name: Specify the name of the root package to be used for the generated business components that model the flexfield usage.

   • BI Flattened Fact Name: If the flexfield is enabled for Oracle Business Intelligence and you know the Oracle Business Intelligence object that this flexfield should be mapped to when the flexfield is imported into Oracle Business Intelligence, specify the name of the object.

     For more information about Oracle Business Intelligence, see Preparing Descriptive Flexfield Business Components for .

9. Click Next, and click Next again.
10. On the Summary page, optionally select Extract seed data for the flexfield to create a seed data file for uploading the registration information into other implementations. For more information, see Loading Seed Data.
11. If you are ready to create business components for the flexfield, select Launch Flexfield Business Components Wizard.
12. Click Finish.

23.2.6 How to Register Extensible Flexfield Parameters

A flexfield parameter is a declared public variable, which can be used to designate which attributes of eligible entity objects that are related to the flexfield can be used to pass external reference data to flexfield segments. These entity object attributes could, in turn, take their values from column values, constant values, session attributes, and so forth.

A flexfield may have zero, one, or many flexfield parameters defined, each one representing a specific type of information that is useful to that flexfield. Implementors can use the parameters to define defaults and value set validation for the flexfield segments.

Some or all of these types of data sources can be referenced in the WHERE clauses for table value sets.

in the following ways:

• At row creation time to provide default segment values.

• In derived segments, which are global, context, or context-sensitive segments for which values are derived from an external reference data source, causing its values to automatically change to reflect any new reference data values.

• In the WHERE clauses for table value sets.

Note:

Although a flexfield parameter is associated with a flexfield in metadata, it is not connected with any specific segment in the flexfield. Rather, it serves as a variable through which flexfield segments can access reference data from other sources.

Every flexfield parameter must be mapped to an appropriate entity object attribute at design time. In this way, implementors are guaranteed that the parameters will always be mapped to entity object attributes, and they can use the parameters as needed.

When you create business components for a descriptive flexfield, you will be required to map each parameter associated with that flexfield to an attribute of the entity object that you are creating. The values accessed from reference data sources by these parameters are then available for you to use in your application. Many of the core (nonflexfield) fields on a page can serve as reference fields.

Consider the example of an Expense Lines entity object with the core fields of Expense Line ID, Expense Date, Amount, Description, and Expense Type. If the flexfield has an ExpenseType parameter that is mapped to the Expense Type field, an implementor can configure the context segment to derive its value from the ExpenseType parameter.

To implement descriptive flexfield parameters, you must map them to the appropriate entity object attributes at design time and configure them. For more information, see Creating Descriptive Flexfield Business Components and How to Configure Descriptive Flexfield Parameters.

To provide flexfield parameter values at runtime, the base implementation of the context entity object must override the method getFlexfieldParameterValue of oracle.apps.fnd.applcore.oaext.model.OAEntityImpl. Yu must handle every flexfield parameter in the overriding method. This guarantees that the parameters always contain the most up-to-date information.

The overriding method must return an object of appropriate type based on the flexfield parameter data type, as shown in the following table.

Table 23-1 Matching flexfield parameter types to data object types

Flexfield Parameter Type	Return Data Object Type
Text	java.lang.String
Number	java.math.BigDecimal
Date	java.sql.Date
Timestamp	java.sql.Timestamp

The following code sample shows how to provide flexfield parameter values at runtime by overriding the getFlexfieldParameterValue method of the context entity object.

Example 23-1 Providing flexfield parameter values at runtime

public class BaseContextEOImpl extends OAEntityImpl{  @Override  public Object getFlexfieldParameterValue(final String localFlexID,                                           final String paramCode)  {    if ("EXPENSE_TYPE".equals(paramCode))    {      return getAttribute("ExpenseType");    }    else if ("EXPENSE_AMOUNT".equals(paramCode))    {      Double amount = (Double) getAttribute("ExpenseAmount");      return (amount == null ? null : new java.math.BigDecimal(amount));    }    else    {      return super.getFlexfieldParameterValue(localFlexID, paramCode);    }  }}                

If you used the Flexfield Registration Metadata wizard to define and register the flexfield, then you might have already defined the parameters. Otherwise, you can edit the flexfield using the Flexfield Registration Metadata wizard or the setup APIs.

23.2.6.1 Use the Flexfield Registration Metadata Wizard to Register a Flexfield Parameter

You can use the Edit flexfield usage operation from the Flexfield Registration Metadata Wizard to register flexfield parameters.

To register a parameter using the Flexfield Registration Metadata wizard:

1. From the File menu, choose New.

2. In the New Gallery, expand Business Tier, select ADF Business Components and then Flexfield Business Components, and click OK.

3. On the Choose Operation page of the Flexfield Registration Metadata wizard, select Edit Flexfield Usage, and then click Next.

4. To display available usages, provide a value for Application, Code, or Table. You can use a wildcard character, such as a percent sign (%), to match on similar values.

5. Select the primary usage of the flexfield for which you want to add the parameters.

6. Click Next until you are on the Parameters page.

7. On the Parameters Page, optionally define parameters for the entity object attributes that can be used to pass external reference data to flexfield segments.

8. Click Next.

9. On the Summary page, optionally select Extract seed data for the flexfield to create a seed data file for uploading the registration information into other implementations. For more information, see Loading Seed Data.

10. If you are ready to create business components for the flexfield, select Launch Flexfield Business Components Wizard.

11. Click Finish.

23.2.6.2 Register a Flexfield Parameter Using the Setup APIs

23.3 Create Descriptive Flexfield Business Components

Before you can use a descriptive flexfield in your application, you must use the Create Flexfield Business Components wizard to generate flexfield business components for the flexfield. The wizard generates a base view object that is based on the information in the flexfield metadata. After the initial flexfield registration, and before any configuration is completed, the base view object has at least two attributes: the primary key attribute, which links the flexfield view object to the product view object, and the context attribute, which serves as the discriminator.

When implementors configure the flexfields by defining global and context-sensitive segments, the base view object is regenerated and additional flexfield view objects are generated. Figure 23-8 shows an example of the configured ADF Business Components. The product view object contains only the nonflexfield attributes. The base view object contains the primary key attribute, the context attribute, and global attributes. The base view object is extended to define view object rows based on the configured context values. Each context value requires a subtype view object definition that represents the structure of the rows with that context value, as described in How Descriptive Flexfields Are Modeled in .

Figure 23-8 Descriptive Flexfield Modeled as ADF Business Components Component

Note:

The product view object might contain other attributes. However, the product view object must not include flexfield view object attributes.

None of the flexfield view objects contains the fixed (nonflexfield) columns.

No Java implementation classes are generated for descriptive flexfield view objects. The product view object may or may not have Java implementation classes.

23.3.1 How to Create Descriptive Flexfield Business Components

You use the Create Flexfield Business Components wizard to create the flexfield business components for a flexfield's usage.

The business components generated will replace any existing ones that are based on the same flexfield usage.

Before you begin:

• Ensure that you have added the Applications Core library to your project as described in Setting Up Your JDeveloper Application Workspace and Projects .

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

  For information about customization layers, see the "Understanding Customization Layers" section in the Extensibility Guide for Developers .

• Verify that the entity object that will be used as the data source for the business component meets the following requirements:

  • All flexfield columns are included in the entity object. In general, all columns should be included.

  • A primary key is defined for the entity object. If an entity object is going to be used to create new application transaction rows, a default primary key must be programmed.

  • All VARCHAR2 columns used for descriptive flexfield attributes are mapped to data type java.lang.String.

  • All number columns used for descriptive flexfield attributes are mapped to data type java.math.BigDecimal.

  • All date columns used for descriptive flexfield attributes are mapped to data type java.sql.Date.

  • All timestamp columns used for descriptive flexfield attributes are mapped to data type java.sql.Timestamp.

• Register the flexfield usage's entity object, package name, and object name prefix. For more information, see How to Register Entity Details.

To create descriptive flexfield business components:

1. Build your project to ensure that the entity objects are available in classes. The modeler relies on what is in your classes.
2. From the File menu, choose New.
3. In the New Gallery, expand Business Tier, select ADF Business Components and then Flexfield Business Components, and click OK.
4. On the Flexfield page of the Create Flexfield Business Components wizard, select Descriptive from the Type dropdown list as shown in Figure 23-9.

   Figure 23-9 Create Flexfield Business Components Wizard — Flexfield Page

   

5. In the Application field, specify the full name of the application to which your descriptive flexfield belongs.

   You can browse for the name, and filter by ID, Short Name, or Name.

6. In the Code field, specify the code of the descriptive flexfield you want to use.

   You can browse for and filter by Code.

7. In the Usage section, select the table row that contains your desired descriptive flexfield usage. The descriptive flexfield usage can be one of two possible types:

   • The primary usage of the descriptive flexfield on the product table where it was originally defined. Every descriptive flexfield has one primary usage.

   • A secondary usage of the descriptive flexfield on a product table, including the one on which it was originally defined. Zero or more secondary usage instances can be defined for a given flexfield, each one potentially on a different product table. You can identify secondary usage instances by the presence of the prefix (Reuse) in the Description field.

8. Click Next.
9. On the Path page, select the path of the directory structure in which to create the flexfield business components and click Next.
10. On the Entity Object page, select the entity object to use as the data source for the descriptive flexfield, as shown in Figure 23-10.

    Figure 23-10 Create Flexfield Business Components Wizard — Entity Object Page

    

    The entity object you select must include all of the attributes representing the columns that are reserved for the descriptive flexfield.

    Note:

    If you select a polymorphic entity object, ensure that the InheritPersonalization property for every subtype entity is set to true.

    Descriptive flexfield attributes will be validated by the entity object along with its other attributes.

11. If the entity object for the descriptive flexfield has attributes that are defined as transient (not based on database table columns), then select The names of the flexfield attributes match the names of registered columns exactly; do not check the underlying columns.

    When an attribute of a descriptive flexfield entity object is transient, there is no matching underlying column name. When you select this option, the system will match the entity object attribute names to the descriptive flexfield column names, and use the matching attributes to access the flexfield data. Ensure that the entity object has a full set of attributes with matching names before you select this option.

    This entity object must be registered under the primary usage. There is no need to register another table for this purpose, even if the entity object is based on some other table. For more information, see How to Register Entity Details.

    Note:

    If the entity object with transient descriptive flexfield attributes is not based on the primary usage, the transient attributes must be named using the same prefix as the other attributes of that entity object (and the corresponding table columns). For more information, see How to Reuse a Descriptive Flexfield on Another Table.

    Caution:

    The Create Flexfield Business Components wizard is case-sensitive. All column names — and the names of the flexfield entity object attributes associated with them — must be uppercase.

12. Click Next.
13. The Naming page displays the entity object's package name and object name that you registered for the usage, as described in How to Register Entity Details. Click Next.
14. On the Parameters page shown in Figure 23-11, map each flexfield parameter to the entity object attribute that will be the data source for the parameter.

    Parameters are not a requirement for descriptive flexfields. If no parameters are defined for the descriptive flexfield that you are working with, the Parameters page will display a message to that effect. However, if any parameters are defined and associated with a descriptive flexfield, you must map each parameter to an entity object attribute before you can use the flexfield in your application.

    Figure 23-11 Create Flexfield Business Components Wizard — Parameters Page

    

    The names in the Parameter Code column represent parameters that have been defined for the descriptive flexfield. For each parameter listed, select the entity object attribute from the Entity Attribute Name dropdown list to use as the data source for that parameter.

    The entity attributes in the dropdown list include the following:

    • Attributes that are part of the entity object you selected as the flexfield data source.

    • Attributes that are part of any entity object that is directly associated with the flexfield entity object through an accessor.

    • Attributes that are part of any entity object that is indirectly associated with the flexfield entity object through a chain of accessors and entity objects.

    Note:

    An entity attribute is available on this list only if all the accessors in the chain to the attribute have an underlying association cardinality of 1-to-1 or many-to-1.

    The path through the chain of accessors to each available entity attribute is displayed using the following notation:

    [accessorname1                      .[accessorname2                      .]...]attributename                    

    Although it is not visible, the name of the previously selected flexfield entity object is implied as the first element in the chain, followed by zero or more accessor names, then the target entity attribute name. The names of the entity objects in this chain are also implied.

    Caution:

    • Flexfield parameters can be used only with segments of the same Java type. The data type of each entity attribute you select must match the data type shown for the parameter.

    • For any flexfield segment value that is derived from a parameter, the derivation happens only when the value of the mapped attribute is updated. Therefore, if you intend for customers to use a parameter for derivation, then the attribute that you map the parameter to must be updatable. If the parameter's value must come from a reference-only entity, then create an updatable transient entity attribute and assign that entity to the flexfield parameter.

15. When all of the defined parameters are mapped, click Next.
16. On the Summary page, click Finish.

    Note:

    This wizard might fail with a "ClassNotFound" exception message. This indicates that one or more required libraries have not been automatically included in your project. You can resolve this issue by manually adding any missing libraries; then you can complete this procedure successfully.

17. Refresh the project to see the newly created flexfield business components in the Application Navigator. The components are in the package that you registered for the flexfield usage and are named using the registered prefix.

23.4 Create Descriptive Flexfield View Links

A view link is needed whenever a product view object references your descriptive flexfield. The product view object and the flexfield base view object are linked through their primary keys.

23.4.1 How to Create Descriptive Flexfield View Links

You create a view link to connect your product view object with the flexfield view object. After you have created the view link, you can use the view object to add the flexfield to an application page.

Before you begin:

1. Create the master view object, which contains only nonflexfield attributes.

2. Create the flexfield business components for the descriptive flexfield as described in How to Create Descriptive Flexfield Business Components.

To create a descriptive flexfield view link:

1. From the File menu, choose New.
2. In the New Gallery, go to Business Tier > ADF Business Components and select Flexfield View Link.
3. Click OK to access the Create Flexfield View Link wizard, as shown in Figure 23-12.

   Figure 23-12 Create Flexfield View Link Wizard — Name Page

   

4. On the Name page, from the Package dropdown list, specify a package for the view link.

   Caution:

   You cannot move the view link to a different package after you create it. Instead, you must delete the view link and re-create it with the new package name.

5. In the Name field, enter a name for the view link.
6. Click Next. The View Objects page appears, as shown in Figure 23-13.

   Figure 23-13 Create Flexfield View Link Wizard — View Objects Page

   

7. In the Select Source View Object tree, expand the available objects from your current project and select the master view object.
8. In the Select Destination Flexfield tree, expand the application and select a destination flexfield usage.
9. In the View Link Accessor Name field, enter an appropriate name for the view link accessor.
10. Click Next.
11. On the Source Attributes page, click Finish.

    For descriptive flexfields, the Source Attributes page is informational only. The wizard uses the primary key attributes of the source view object to define the view link.

    Note:

    You can skip the Properties page because view link-specific properties are not supported.

12. On the Summary page, click Finish.

23.5 Nest the Descriptive Flexfield Application Module Instance in the Application Module

You must nest the descriptive flexfield application module instance under the product application module before you can incorporate the descriptive flexfield usage into the UI.

You need to nest only one flexfield application module for a flexfield usage, even if two or more view links exist for the same flexfield usage.

23.5.1 How to Nest the Descriptive Flexfield Application Module Instance in the Application Module

You use the overview editor for your application module to nest the descriptive flexfield application module instance. The descriptive flexfield application module instance that you nest in the product application module shares the same transaction and entity object caches as the application module.

Before you begin:

1. You should have already created the product application module. For 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 .

2. Create the master view object, which contains only nonflexfield attributes.

3. Create a flexfield business component for the descriptive flexfield usage as described in How to Create Descriptive Flexfield Business Components.

To nest the descriptive flexfield application module instance in the product application module:

1. In the Application Navigator, double-click the product application module.
2. Click the Data Model navigation tab.
3. On the Data Model Components page, expand the Application Module Instances section, as shown in Figure 23-14.

   Figure 23-14 Application Module — Application Module Instances Section

   

4. In the Available tree, find and expand the applicationModule instance under the flexfield usage's package. This is the package that you specified when you defined the entity details, as described in How to Register Entity Details.
5. Select the application module for the descriptive flexfield and move it to the Selected tree.

   This application module was created when you created the flexfield business component and was named using the prefix that you specified when you defined the usage's entity details, as described in How to Register Entity Details. For example, if you registered the CasesDFF prefix, the application module name is CasesDFFAM.

   The New App Module Instance field under the list shows the name that will be used to identify instance. You can change this name.

23.6 Add a Descriptive Flexfield View Object to the Application Module

You must add a flexfield view object instance that reflects the hierarchy of the view link that you created in How to Create Descriptive Flexfield View Links to the application module for your application.

23.6.1 How to Add a Descriptive Flexfield View Object Instance to the Application Module

Edit the product application module to add the flexfield view object.

Before you begin:

1. You should have already created the product application module. For 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 .

2. Create the master view object, which contains only nonflexfield attributes.

3. Create the flexfield business components for the descriptive flexfield usage as described in How to Create Descriptive Flexfield Business Components.

4. Create the flexfield view link as described in How to Create Descriptive Flexfield View Links.

To add a descriptive flexfield view object to the product application module:

1. In the Application Navigator, double-click the product application module.
2. Click the Data Model navigation tab.
3. In the View Object Instances section, select the master view object from the Available View Objects tree and click the right arrow to add it to the Data Model tree. Next, select the child view object for the flexfield view link and click the right arrow to add it to the Data Model tree, as shown in Figure 23-15.

   Figure 23-15 Application Module — View Object Instances Section

   

23.7 Add Descriptive Flexfield UI Components to a Page

To include a descriptive flexfield on an application page, add the flexfield UI component to the page, and then configure the properties of the UI component.

To add a descriptive flexfield UI component, you add the component to a page in the one of the following configurations:

• As part of a form component.

• As part of a table component, with the context-sensitive segments of the flexfield presented in a detailStamp facet. This is the typical configuration, which allows for the full range of possible values in the context segment.

• As part of a table component, with context-sensitive segments of the flexfield presented as columns. To use this configuration, you must guarantee that the flexfield context segment will have the same value in all rows of the table.

Note:

You cannot use a descriptive flexfield in a tree table component.

If your ADF Table is in an Applications Table component, you must add the following functionality to the UI:

• Create Row and Delete Row functionality if you are using your own CreateInsert button to create new rows.

• Empty table handling if you are using a custom createInsert method.

• Dynamic refresh of the context-sensitive segment columns whenever the Applications Table component is refreshed by another component, such as a button or a search query.

Note:

The following procedures assume that you are using the data-first approach of adding flexfields to your application. The UI-first approach is also available, but is not documented here. For more information, see the Introduction to Placeholder Data Controls section in the Developing Fusion Web Applications with Oracle Application Development Framework

23.7.1 How to Add a Descriptive Flexfield UI Component to a Form

To add a descriptive flexfield UI component to a form:

1. From the Data Controls panel, select the master view object and drag it onto the page to create the UI for the master view object.
2. When prompted, select ADF Form or select Applications > Panel.
3. In the Data Controls panel, expand the master view object and find the flexfield view object, as shown in Figure 23-16.

   Caution:

   You must use the flexfield view object that is the child of the master view object. Do not use the flexfield view object from the flexfield's application module data control.

   Figure 23-16 Flexfield View Object Nested Under Master View Object

   

4. Drag the flexfield view object onto a form, and select the appropriate flexfield UI component.

   Tips:

   • If you place the flexfield in its own tab, header, or subheader, and you cannot provide a specific label for the region, consider using the label "Additional Information," which is the standard generic label in such a case for Oracle Fusion Applications.

   • If a descriptive flexfield is in a region, such as a header, subheader, or tab, that does not contain nonflexfield fields, there is a possibility that the implementor will not use the flexfield segments and the region will be empty. To avoid the display of an empty region on the page, add controlling logic to hide the region if the implementor has not defined the segments that appear in the region. For information about how to determine if a segment has been defined, see How to Determine Whether Descriptive Flexfield Segments Have Been Defined. For information about using an EL expression to hide the region, see the Creating EL Expressions section in the Developing Web User Interfaces with Oracle ADF Faces

   • You can place the segments in a multiple-column layout. Use a multiple-column layout when the number of segments that will be added by the implementor is unknown and you anticipate that a large number of segments will be used. Otherwise, a flexfield with several segments will take up a large amount of space and the end user will have to scroll to see any fields that appear below the flexfield.

5. Optionally, to add Create Row and Delete Row functionality to the UI, drag the appropriate operation of the master view object from the Data Controls panel onto the page.

Tip:

You can configure the descriptive flexfield UI component to present multiple descriptive flexfield rows using the Panel Form Layout component, with each row's content based on a different context value. For more information, see the Arranging Content in Forms section of the Developing Web User Interfaces with Oracle ADF Faces .

23.7.2 How to Add an Unrestricted Descriptive Flexfield UI Component to a Table

To add an unrestricted descriptive flexfield UI component to a table:

1. From the Data Controls panel, select the master view object and drag it onto the page to create the UI for the master view object.
2. When prompted, select ADF Table or Applications > Table. You must select the Row Selection option, and set the appropriate width. Follow the wizard to create tree structure, pathStamp, and nodeStamp components.
3. In the Data Controls panel, expand the master view object and find the flexfield view object.

   Caution:

   You must use the flexfield view object that is the child of the master view object. Do not use the flexfield view object from the flexfield's application module data control.

4. Drag the flexfield view object onto the table on the design tab, as shown in Figure 23-17, and select Oracle Descriptive Flexfield Column as the UI component. This creates the base flexfield column in the table that the global segments will render.

   Figure 23-17 Descriptive Flexfield Dropped Into a Table

   

   Caution:

   Do not drop the flexfield view object into an existing column. The displaying of descriptive flexfields in the cell of a table column is not supported.

5. Create a detail region (detailStamp facet) if the table does not have one, as shown in Figure 23-18.

   Figure 23-18 Detail Region — detailStamp Facet

   

6. Add a panel layout control to the detailStamp facet if you do not already have one.
7. Drag and drop the same flexfield view object into the detail region on the Source tab or the structure view as shown in Figure 23-19; this creates fields for the context-sensitive segments.

   Figure 23-19 Descriptive Flexfield Dropped into a Detail Region

   

23.7.3 How to Add Descriptive Flexfield Context-Sensitive Segments to a Table as Columns

Typically, context-sensitive segments in a table are visible only in a detailStamp facet. This is because the flexfield context segment can contain a different value in each table row; therefore the set of associated context-sensitive segments that appears can vary from row to row. There is no way to present all of these varying results in a predefined column format within a single table.

However, if you can guarantee that a given context segment in every row of the table will always contain the same value for a given application page, the resulting combination of corresponding context-sensitive segments in each row will remain constant. In this circumstance the context-sensitive segments can be displayed as table columns.

For example, if the context segment is a country code, and the purpose of this application page is to manage only Italian tax data, then the context value should always be IT. The table columns for the context-sensitive segments will always be displayed in the configuration appropriate to the Italian tax system.

Before you begin:

1. Create the descriptive flexfield view object as described in How to Create Descriptive Flexfield Business Components.

2. Create the view link as described in How to Create Descriptive Flexfield View Links.

3. Nest the descriptive flexfield application module in the product application module as described in How to Nest the Descriptive Flexfield Application Module Instance in the Application Module.

4. Add the view object instance to the application module as described in How to Add a Descriptive Flexfield View Object Instance to the Application Module.

To add a descriptive flexfield UI component to a table as a column:

1. From the Data Controls panel, select the master view object and drag it onto the page to create the UI for the master view object.
2. When prompted, select ADF Table or Applications > Table. You must select the Row Selection option, and set the appropriate width.
3. In the Data Controls panel, expand the master view object and find the flexfield view object.

   Caution:

   You must use the flexfield view object that is the child of the master view object. Do not use the flexfield view object from the flexfield's application module data control.

4. Drag the flexfield view object onto the table on the design tab as shown in Figure 23-17, and select Oracle Descriptive Flexfield Column as the UI component. This creates the base flexfield column in the table.

   Caution:

   Do not drop the flexfield view object into an existing column. The displaying of descriptive flexfields in the cell of a table column is not supported.

5. Edit the JSP source code for this page, and remove the following attribute from the <fnd:descriptiveFlexfield> tag:

   mode="global"                    

   See Table 23-2 for information about the mode attribute.

6. Add a WHERE clause or view criteria to the master view object to enforce the same predetermined context value for all rows of the table.

   If the context segment will be visible on the page, you must configure the segment to be read-only so end users cannot modify it. For more information, see How to Configure Segment-Level UI Properties.

23.7.4 How to Add Create Row and Delete Row Functionality to the Page

If your ADF Table is wrapped in an Applications Table component, and if you are using your own Create Insert button to create new rows, you must complete the following steps.

You do not need to complete these steps if new rows are created using the Applications Table's New button or the New option on the Actions menu.

Caution:

If you enable end users to add new flexfield rows to the UI table, you can permit them to enter their own unique key values for a new row. However, you must provide a programmatically generated primary key value for the new row, otherwise it will generate an error.

To add Create Row and Delete Row functionality to the page:

1. From the Data Controls panel, drag the appropriate operation of the master view object (such as CreateInsert) onto the page.
2. Delete the newly created button, but not its pageDef entry. Example 23-2 shows an example of the pageDef entry.
3. Add a new button to the layout.
4. In the Property Inspector for the button, expand the Common section and set the ActionListener to the EL expression for the method binding. For example, #{myBean.customCreateInsert}.

   Example 23-2 shows how the executables element of the page definition might look. Dff1RefInstanceIterator is the iterator of the master view object.

5. To ensure that new descriptive flexfield rows appear in the UI, add code to the application page (in the Invoke Application phase or just before the Render Response phase) to set the state of each newly created row to STATUS_NEW, as demonstrated in Example 23-3.
6. Add code to the custom createInsert method to handle an empty table as described in How to Add a Row to an Empty Table in a Custom createInsert Method

Example 23-2 Executables Element of Page Definition Code

<executables>    <iterator Binds="Dff1RefInstance" RangeSize="25" DataControl="Dff1RefAMDataControl" id="Dff1RefInstanceIterator"/>    <iterator Binds="Dff1Instance" RangeSize="25" DataControl="Dff1RefAMDataControl" id="Dff1InstanceIterator"/> </executables>                

Example 23-3 Code to Set New Table Row State to STATUS_NEW

public void invokeMethod(String expr, Class[] paramTypes, Object[] params)  {   FacesContext fc = FacesContext.getCurrentInstance();   MethodBinding mb = fc.getApplication().createMethodBinding(expr,paramTypes);   return mb.invoke(fc,params); }  public void customCreateInsert(ActionEvent actionEvent) {   invokeMethod("#{bindings.CreateInsert.execute}",ActionEvent.class,actionEvent);     FacesContext fCtx = FacesContext.getCurrentInstance();   javax.faces.application.Application app = fCtx.getApplication();   ELContext elCtx = fCtx.getELContext();   int index = 0;   Row coreVORow =      ((RowSetIterator)app.evaluateExpressionGet(fCtx,     "#{bindings.Dff1RefInstanceIterator.rowSetIterator}",     RowSetIterator.class)).getRowAtRangeIndex(index);     coreVORow.setNewRowState(Row.STATUS_NEW); }                

Caution:

• If you enable end users to add new flexfield rows to the UI table, you must ensure that the default value of the new row's context segment is your predetermined value, matching the existing rows.

• You can permit end users to enter their own unique key values for a new row. However, you must provide a programmatically generated primary key value for the new row, otherwise it will generate an error.

• The context segment value in any existing row must not change at runtime. You must enforce this by hiding the context segment or by configuring it as read-only. For more information, see How to Configure Flexfield-Level UI Properties and How to Configure Segment-Level UI Properties.

23.7.5 How to Add a Row to an Empty Table in a Custom createInsert Method

If you are using a custom createInsert method to add rows to an Applications Table component, you must include code similar to Example 23-4 to handle an empty table. Replace FirstRowInTable with logic to determine whether the table is empty and the new row is the first row in the table.

Example 23-4 Handling Empty Tables in a Custom createInsert Method

if (FirstRowInTable                  &&             BindingUtil.getCustomProperty(table, "flexenabled") != null)         {            List<UIComponent> columns = table.getChildren();           if (columns != null)           {             for (UIComponent column: columns)             {               if (column.getChildCount() > 0)               {                 UIComponent c1 = column.getChildren().get(0);                 if (c1 instanceof DescriptiveFlexfield)                 {                   ((DescriptiveFlexfield) c1).createDynamicColumns();                 }               }             }           }         }                

23.7.6 How to Dynamically Refresh a Descriptive Flexfield

If your flexfield is in an ADF Table that is wrapped in an Applications Table component that is refreshed by another component, such as a button or a query, then you must add functionality to dynamically refresh the flexfield segments.

To refresh the flexfield segments based on the current iterator rowset data, create a listener method in the flexfield's backing bean and bind the listener to the component that is initiating the table refresh. The listener must first call the default listener and then call DescriptiveFlexfield.updateFlexColumns(RichTable), where RichTable is the binding for the table that contains the flexfield.

Example 23-5 shows an example of a custom flexfield handler for a query event. Example 23-6 shows the binding of the custom flexfield handler to the query component.

Note:

You do not need to handle flexfield refresh for standard Applications Table create and delete operations. However, custom create and delete operations must handle the refreshing of flexfields.

Example 23-5 Flexfield Listener

public void customDffSearchQueryListener(QueryEvent queryEvent) {   FacesContext context = FacesContext.getCurrentInstance();   String queryListener =     "#{bindings.Dff3RefVOCriteriaQuery.processQuery}";   ELContext elctx = context.getELContext();   ExpressionFactory elFactory =     context.getApplication().getExpressionFactory();     MethodExpression queryMethod =     elFactory.createMethodExpression(elctx, queryListener, Object.class,     new java.lang.Class[] { QueryEvent.class });   queryMethod.invoke(elctx, new Object[] { queryEvent });   // appTable is the handle of the binding for the table   // that contains the flexfield   DescriptiveFlexfield.updateFlexColumns(appTable); }                

Example 23-6 Binding the Flexfield Listener to the Search Query

<af:query id="qryId1"   headerText="#{applcoreBundle.QUERY_SEARCH_HEADER_TEXT}"   disclosed="true"   value="#{bindings.criteriaQuery.queryDescriptor}"   model="#{bindings.criteriaQuery.queryModel}"   queryListener="#{backingBeanScope.dffBean.customDffSearchQueryListener}"   queryOperationListener="#{bindings.DffCriteriaQuery.processQueryOperation}"   resultComponentId="::AT2:_ATp:ATt2"/>                

23.7.7 What Happens When You Add a Descriptive Flexfield to a Page

Descriptive flexfield segments appear on a form as a widget with a implementor-defined label, just as core fields do. In a table, the label of the flexfield segment is the column header and the values are within each cell of the column.

Figure 23-20 shows an example of a descriptive flexfield used in a form on an application page.

Figure 23-20 Example of a Descriptive Flexfield in a Form

Figure 23-21 shows an example of a descriptive flexfield used in a table on an application page:

Figure 23-21 Example of a Descriptive Flexfield In a Table

Note:

Descriptive flexfield segments always appear as form fields or table columns in the same order that their corresponding attributes appear in the underlying view object.

23.8 Configure Descriptive Flexfield UI Components

You can control your descriptive flexfield's behavior in the application UI by modifying properties at the flexfield level and the segment level, configuring descriptive flexfield parameters, and configuring the flexfield to handle value change events.

23.8.1 How to Configure Flexfield-Level UI Properties

To configure flexfield-level properties:

• Select the descriptive flexfield's UI component on the page and modify its properties in the Property Inspector, as shown in Figure 23-22.

  Figure 23-22 Descriptive Flexfield Property Inspector

  

The significant properties on the Common, Data, Style and Behavior property tabs are listed in Table 23-2.

Table 23-2 Descriptive Flexfield Properties

Tab > Property	Description
Common > Id	This is the ID of the flexfield.
Common > Rendered	This indicates whether the flexfield is rendered on the page. Values can be True (default) or False. EL expressions are allowed.Foot 1
Common > Value	This is the value of the flexfield. This should be an EL expression pointing to an iterator object. The iterator value must be statically declared in the page definition. This field is also visible on the Data tab.
Data > Accessor	This property is the name of the accessor between the product view object and the flexfield view object.
Data > Category	This defines which category will be rendered on the page. The category can be set on each attribute's custom property.
Style > StyleClass	This property is the style class of the flexfield. A style class allows you to group a set of inline styles.
Style > InlineStyle	This is the inline style of the component. The InlineStyle property is a string of CSS styles that can set individual properties such as background color, font style, or padding.
Behavior > Read-Only	This indicates whether the flexfield is rendered as read-only. Values can be True or False (default). EL expressions are allowed.
Behavior > Mode	This defines the UI mode of the descriptive flexfield component, to render all of the segments or just some of them. Values can be: No value (default): render all of the descriptive flexfield segments. global: render only the global segments of the flexfield. This is the default value for a descriptive flexfield inside a table column, to generate subcolumns for the global segments. contextSensitive: render only the context-sensitive segments of the flexfield (including the context segment). This is the default value for a descriptive flexfield inside a table detail region, to render the context values.
Behavior > partialTriggers	This property is the IDs of the components that should trigger a partial update in the flexfield (String[]). EL expressions are allowed.
Behavior > valueChangeListener	This property is a method reference to a value change listener (javax.faces.el.MethodBinding). It requires an EL expression.
Behavior > binding	This is an EL reference that will store the component instance on a bean (oracle.apps.fnd.applcore.flex.ui.DescriptiveFlexfield). This property requires an EL expression.
Other > showRequired	This indicates whether to bypass client-side validation of required segments that have null values. Values can be True or False (default). If the value is True, the end user can submit a form with null values in the fields for required segments (the segment fields that have asterisks). EL expressions are allowed. For related information about server-side validation of required segments, see How to Prevent Validation of Required Segments.

^Footnote 1

For a descriptive flexfield that was added as table columns, you cannot control this property on a row-by-row basis. It must be set to apply to the entire column.

23.8.2 How to Configure Segment-Level UI Properties

Descriptive flexfields support finer control of segments in the UI through the following segment-level UI properties:

• Rendered: This boolean property indicates whether the segment is visible on the application page. You can set this property with a literal value or an EL expression.

• Required: This boolean property indicates whether the segment must have a value. You can set this property with a literal value or an EL expression.

• ReadOnly: This boolean property indicates whether end users can modify the segment. You can set this property with a literal value or an EL expression.

• Visible: This boolean property specifies whether the segment is displayed in the page or is hidden. You can set this property with a literal value or an EL expression.

• AutoSubmit: This boolean property specifies whether a component automatically submits when a segment's value changes. You can set this property with a literal value or an EL expression.

• Label: This string property provides a display label for a segment.

• ShortDesc: This string property provides a short description of a segment.

• Columns: This integer property specifies the width of the control in terms of the default font size of the browser. You can set this property with a literal value or an EL expression.

The default values of these properties are derived from the flexfield metadata, but you can override them by inserting the following flexfield hint components from the Applications page of the Component Palette:

• Flexfield Context Segment Hints: Use this component to configure the context segment.

• Flexfield Segment Hints: Use this component to configure all global segments or to configure all context-sensitive segments. Also use this component as a container for Flexfield Segment Hint.

• Flexfield Segment Hint: Nest this component in a Flexfield Segment Hints component to configure an individual global or context-sensitive segment.

Note:

If you set a segment's Required property to True, for validation purposes you cannot override this by resetting it to False in the flexfield hint component. You can, however, do the reverse: Change a nonrequired segment to required in the flexfield hint component.

For information about using EL expressions, see the Creating ADF Data Binding EL Expressions section in the Developing Fusion Web Applications with Oracle Application Development Framework .

Before you begin:

Add the descriptive flexfield to the page as described in Adding Descriptive Flexfield UI Components to a Page.

23.8.2.1 Configure a Context Segment

Use Flexfield Context Segment Hints to set the Visible, ReadOnly, Rendered, Required, Label, ShortDesc, Columns, and AutoSubmit UI properties for a context segment.

To configure a context segment:

1. From the Applications page of the Component Palette, drag Flexfield Context Segment Hints and drop it as a child of the Descriptive Flexfield component.
2. In the Property Inspector, set the context segment's UI properties.

23.8.2.2 Configure All Global Segments

Use Flexfield Context Hints to set the Visible, ReadOnly, Rendered, and Required properties to the same values for all the global segments.

To configure all global segments:

1. From the Applications page of the Component Palette, drag Flexfield Segment Hints and drop it as a child of the Descriptive Flexfield component.
2. In the Property Inspector, set the Visible, ReadOnly, Rendered, and Required properties.
3. Ensure that the ContextCode property is blank.

Caution:

For a descriptive flexfield that was added as table columns, you cannot configure the Rendered property of global segments on a row-by-row basis. It must be set to apply to the entire column.

23.8.2.3 Configure Individual Global Segments

Use a Flexfield Segment Hint component nested in a Flexfield Segment Hints component to set the Visible, ReadOnly, Rendered, Required, Label, ShortDesc, Columns, and AutoSubmit UI properties for a global segment.

You typically set the ReadOnly property to True if a default value is assigned to that segment, and you do not want end users to choose a value other than the default. Do not set both Required and ReadOnly to True if the segment does not have a default value.

Before you begin:

From the Applications page of the Component Palette, drag Flexfield Segment Hints and drop it as a child of the Descriptive Flexfield component. Do not set any properties.

To configure a global segment:

1. From the Applications page of the Component Palette, drag Flexfield Segment Hint and drop it as a child of Flexfield Segment Hints.
2. In the Property Inspector, set the SegmentCode property.

   Tip:

   To determine the correct value for the SegmentCode property, examine the FND_ACFF_SegmentName attribute of the segment's viewAttribute element in the descriptive flexfield view object.

3. Set the global segment's UI properties.

23.8.2.4 Configure All Context-Sensitive Segments

Use Flexfield Context Hints to set the Visible, ReadOnly, Rendered, and Required UI properties to the same values for all the context-sensitive segments.

To configure all global segments:

1. From the Applications page of the Component Palette, drag Flexfield Segment Hints and drop it as a child of the Descriptive Flexfield component.
2. In the Property Inspector, set the ContextCode property.
3. Set the Visible, ReadOnly, Rendered, and Required properties.

23.8.2.5 Configure Individual Context-Sensitive Segments

Use a Flexfield Segment Hint component nested in a Flexfield Segment Hints component to set the Visible, ReadOnly, Rendered, Required, Label, ShortDesc, Columns, and AutoSubmit UI properties for a context-sensitive segment.

You typically set the ReadOnly property to True if a default value is assigned to that segment, and you do not want end users to choose a value other than the default. Do not set both Required and ReadOnly to true if the segment does not have a default value.

Before you begin:

From the Applications page of the Component Palette, drag a Flexfield Segment Hints and drop it as a child of the Descriptive Flexfield component. Set the ContextCode property.

To configure a context-sensitive segment:

1. From the Applications page of the Component Palette, drag Flexfield Segment Hint and drop it as a child of Flexfield Segment Hints.
2. In the Property Inspector, set the SegmentCode property.

   Tip:

   To determine the correct value for the SegmentCode property, examine the FND_ACFF_SegmentName attribute of the segment's viewAttribute element in the descriptive flexfield view object.

3. Set the context-sensitive segment's UI properties.

23.8.3 How to Configure Descriptive Flexfield Parameters

You must add all the parameters that you have registered for the flexfield to the partialTriggers list so that each parameter's associated UI component is refreshed when its attribute is changed.

Before you begin:

1. Define and register the necessary parameters, if any.

2. Add the descriptive flexfield to the page as described in Adding Descriptive Flexfield UI Components to a Page.

To configure descriptive flexfield parameters:

1. Identify each UI component that corresponds (through the flexfield view object) to an entity object attribute to which a flexfield parameter is mapped, and ensure that the ID attribute of the UI component is set.

   For example, say you mapped the Customer parameter to the entity object Customer_Name attribute, which in turn has a corresponding view object attribute called Customer_Name and is displayed on the page using an inputText field with the prompt "Customer Name". You would ensure that this UI component has an ID, say, customerInputText.

2. In the Behavior section of the Property Inspector for the descriptive flexfield UI component, add the UI component ID to the list in the PartialTriggers field.

   In the previously introduced example, you would add customerInputText to the PartialTriggers list. Example 23-7 shows the source view of the partialTriggers attribute.

Example 23-7 Adding the UI Component ID to the PartialTriggers List

<fnd:descriptiveFlexfield value="#{bindings.Dff1Iterator}" partialTriggers=customerInputText>                

23.9 Testing Flexfields

You can test specified flexfields from JDeveloper using the Run with Flexfields dialog or the Debug with Flexfields dialog. You can also test the flexfields by running the application from an Integrated WebLogic Server instance. For more information, see Testing Flexfields.

23.10 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 the Seed Data Loader.

After you complete the registration process described in How to Register and Define Descriptive 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.

Use the Manage Descriptive Flexfields and Manage Value Sets tasks or use the PL/SQL APIs to create contexts, segments, and value sets, and then use the seed data loader to extract your seed data. To protect flexfield seed data from customer edits, use the PL/SQL flexfield registration API to mark a descriptive flexfield as protected, as described in Using the Setup APIs To Register and Define Descriptive Flexfields. Use the Manage Value Sets task to set the flag to protect a value set.

Only the user with the SEED_DATA_FROM_APPLICATION_USER user name can modify protected flexfields and value sets from the setup tasks, such as the Manage Descriptive Flexfields and Manage Value Sets tasks.

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

23.11 Work with Descriptive Flexfield UI Programmatically

When working with descriptive flexfields programmatically, you might need to know how to do the following tasks:

• Update a descriptive flexfield

• Determine whether flexfield segments have been defined

• Configure a descriptive flexfield to handle value change events

• Configure a flexfield to prevent the validation of required segments.

23.11.1 How to Update a Descriptive Flexfield Programmatically

When you update a flexfield programmatically, you must obtain the same flexfield view row that is used by the UI. You use the getFlexfieldVORowFromEvent method to get a handle to a flexfield view row from the ValueChangeEvent instance.

public static Row getFlexfieldVORowFromEvent(ValueChangeEvent vce);              

Update the context value on the flexfield, not the master view row. Otherwise, the structure will not change. Do not update the entity object directly. The flexfield's structure logic is in the setter of the view row, so do not bypass it.

23.11.2 How to Determine Whether Descriptive Flexfield Segments Have Been Defined

Your application might require information about any global or context-sensitive segments that exist in a descriptive flexfield's metadata before it invokes a UI that includes the flexfield.

There is a view attribute in the descriptive flexfield view object, _FLEX_NumOfSegments, that contains the combined total number of global segments and context-sensitive segments in the flexfield. Its value is in the java.lang.Integer data format. This value may vary depending on the context.

The value of this view attribute is the number of segments defined in the metadata. For a given descriptive flexfield view row, a value of 0 means that only the context segment is available. Whether a segment is displayed is not taken into consideration.

23.11.3 How to Configure a Descriptive Flexfield to Handle Value Change Events

You can configure your application to recognize and respond to changes in individual descriptive flexfield segment values.

You register a value change listener to capture any ValueChangeEvent that occurs. When an end user changes a segment value, the input components associated with the flexfield segments on the application page deliver a value change event, and the listener is called.

Before you begin:

Add the descriptive flexfield to the page as described in Adding Descriptive Flexfield UI Components to a Page.

To configure a descriptive flexfield to handle value change events

1. Create the listener handler as a Java method (usually on a backing bean). Example 23-8 is an example of a method that handles a ValueChangeEvent.
2. Specify the handler method as UI metadata on the flexfield's value change listener property (described in Table 23-2). In the Property Inspector, click the Edit button for the value change listener property, and a wizard appears to help you select an existing event listener or create a new listener. Example 23-9 is an example of the metadata as an EL expression that identifies the dffChangeListener listener from the Java method in Example 23-8.

Example 23-8 Sample Listener Handler Method

public void                  dffChangeListener(ValueChangeEvent valueChangeEvent) {      System.out.println("***** In dffChangeListener()");      System.out.println("getSource() = " + valueChangeEvent.getSource());      System.out.println("getOldValue() = " + valueChangeEvent.getOldValue());      System.out.println("getNewValue() = " + valueChangeEvent.getNewValue());     }                

Example 23-9 Sample EL Expression Identifying dffChangeListener

<fnd:descriptiveFlexfield value="#{bindings.PJCDFF1Iterator}"      valueChangeListener=      "#{managed_DFFHeaderTablePropHandler.dffChangeListener}"      autoSubmit="true">                

For more information about handling value change events, see the Using Input Components and Defining Forms chapter in Developing Web User Interfaces with Oracle ADF Faces .

23.11.4 How to Prevent Validation of Required Segments

Sometimes you might need to bypass server-side validation of a required segment. For example, you might need to enable end users to save a partially filled form for later submission. To bypass server-side validation of a required segment, override the getFlexfieldViewUsageConfiguration method in the class for the master view object to disable this type of validation for the flexfield's view usage and view link accessor. In the case where you need to also bypass client-side validation, additionally set the flexfield's showRequired property to true as described in Table 23-2. When the showRequired property is true, the page displays asterisks next to the required segments to indicate that values are required, but will not perform client-side validation of segments with null values.

The getFlexfieldViewUsageConfiguration method, which is called whenever a flexfield view object is created through either a view link usage or a view link accessor, must accept the name of the view link accessor and must return a Map object.

As shown in Example 23-10, the method must verify that the name of the view object matches the name of the flexfield's master view object and that the name of the view link accessor matches the value passed into the method. If the names match, return a Map that contains a mapping for the key FlexfieldViewObjectImpl.CONF_BYPASS_VALIDATION_REQUIRED. The mapping's value must be boolean. A value of Boolean.TRUE indicates a null value should not cause a validation failure for any of the flexfield's required segments.

Example 23-10 getFlexfieldViewUsageConfiguration Method

@Override protected Map<String, Object>    getFlexfieldViewUsageConfiguration(String accessorName) {   if ("Parts1".equals(getName()) &&      "FndCrmPartsDFFVL".equals(accessorName))   {     Map<String, Object> map = new HashMap<String, Object>(1);     map.put(       FlexfieldViewObjectImpl.CONF_BYPASS_VALIDATION_REQUIRED, Boolean.TRUE);     return map;   }   else   {     return super.getFlexfieldViewUsageConfiguration(accessorName);   } }                

23.12 Incorporate Descriptive Flexfield into a Search Form

You can include descriptive flexfield view object attributes as search criteria in an advanced query search form. This form enables end users to define ad hoc criteria to search for data in the application's master view object and its linked descriptive flexfield view object. End users can select which attributes of the descriptive flexfield view object to use as search criteria.

Note:

If the search form displays the results in a table, the table displays the result set only under the following conditions:

• The end user performs a search.

• The Run Automatically check box for the search form's default search has been selected.

If a result set has not been displayed in the table, the only flexfield columns that appear in the table are the columns for the global segments.

23.12.1 How to Incorporate Descriptive Flexfields Into a Search Form

To incorporate a descriptive flexfield into a search form, use the Edit Query Criteria tab to add view criteria to a view object instance and then drop the view criteria onto the page as an ADF Query Panel with Table component.

To add a descriptive flexfield to a search form:

1. Add view criteria to the product view object instance that uses attributes from the view-linked descriptive flexfield view object, as shown in Figure 23-23.

   Figure 23-23 Edit Query Criteria Tab of View Object View Criteria Definition

   

   1. Enter a name for the view criteria definition and select the view accessor attribute from the master view object. The attributes of the view-linked descriptive flexfield view object appear.

   2. Select the context segment (the discriminator) and use it as the attribute in the view criteria definition.

   3. Select Equals as the Operator and select Literal as the Operand.

   Note:

   To include segments that use ID-based table-validated value sets or translated value sets in a query panel, the query mode must be set to Both to allow both database query and in-memory filtering. The search may be slow if the search results in a large number of rows fetched.

2. Create a new JSPX page in the user interface project.

   Tip:

   Oracle JDeveloper names the user interface project ViewController by default.

3. In the Data Control panel, select the named view criteria that you created previously.

4. Drag and drop the view criteria onto the page as an ADF Query Panel with Table component, as shown in Figure 23-24.

   Figure 23-24 Page with Descriptive Flexfield Search Form

   

5. If the descriptive flexfield appears on the page as a column in a table, perform the following substeps to enable the execution of a saved search when the page is loaded for the first time:

   1. From the Property Inspector for the table in which the flexfield is displayed, obtain the TableId value.

   2. In the Property Inspector for the Query component, set the value of the ResultComponentId property to the TableId value.

6. Run the new search form page and click the Advanced button. When you click Add Fields, only the attributes associated with the base descriptive flexfield view object (global segments) are available as additional criteria. To include the context-sensitive attributes for a context, select the equal to operator for the Context Value criteria item and select a context. The Add Fields list refreshes to include the context-sensitive attributes from the subtype view object for the selected context, as shown in Figure 23-25.

   Note:

   Figure 23-8 illustrates the attributes associated with the base descriptive flexfield view object (global segments) and the context-sensitive attributes.

   Figure 23-25 Descriptive Flexfield Search Form UI

   

   For more information about working with search forms, see the Creating ADF Databound Search Forms chapter of Developing Fusion Web Applications with Oracle Application Development Framework .

23.13 Prepare Descriptive Flexfield Business Components for Oracle Business Intelligence

Oracle Business Intelligence is a comprehensive collection of enterprise business intelligence functionality that provides the full range of business intelligence capabilities including interactive dashboards, full ad hoc, proactive intelligence and alerts, enterprise and financial reporting, real-time predictive intelligence, and more.

Descriptive flexfields are modeled using polymorphic view objects, which are is not compatible with Oracle Business Intelligence. To enable a descriptive flexfield to be used by Oracle Business Intelligence, the corresponding polymorphic view object must be flattened into a usable static form. When you create business components for this descriptive flexfield, the business component modeler recognizes the business intelligence-enabled setting, and a view object that is flattened for business intelligence is generated alongside the standard descriptive flexfield polymorphic view object. You must also slightly modify the process of creating descriptive flexfield view links and application modules.

When the business intelligence-enabled and flattened descriptive flexfield is configured as part of an application, the implementor can select which individual flexfield segments to make available for use with Oracle Business Intelligence. Only the segments that are business intelligence-enabled are included in the flattened view object

23.13.1 How to Enable a Descriptive Flexfield for Oracle Business Intelligence

To enable implementors to perform business intelligence queries on whatever segments they configure for a flexfield, you must business-intelligence enable the flexfield in one of the following ways. A flattened view object is generated only if the descriptive flexfield is business-intelligence enabled.

• Edit the flexfield from the Flexfield Registration Metadata wizard as described in Using the Flexfield Registration Metadata Wizard To Register and Define Descriptive Flexfields , and select the Enable Business Intelligence checkbox.

• Set the BI_ENABLED flag at registration time using the fnd_flex_df_setup_apis.create_flexfield(...) procedure. For information about using this procedure, see What You May Need to Know About the Descriptive Flexfield Setup API.

• Set the BI_ENABLED flag using the fnd_flex_df_setup_apis.update_flexfield(...) procedure. For information about using this procedures, see What You May Need to Know About the Descriptive Flexfield Setup API.

You can optionally provide flattened fact names for the flexfield's entity details, as described in How to Register Entity Details. This helps to automate the process for importing the descriptive flexfield into Oracle Business Intelligence. If you are using fnd_flex_df_setup_apis, you provide the flattened fact name by setting the BI_FLATTENED_FACT_NAME value.

When a descriptive flexfield is business intelligence-enabled, implementors use the Manage Descriptive Flexfields task to enable the descriptive flexfield's segments for business intelligence. Only the segments that are business intelligence-enabled are included in the flattened view object. Administrators must then import the changes into the Oracle Business Intelligence repository to make them available for Oracle Business Intelligence.

23.13.2 How to Flatten the Descriptive Flexfield Model for a Business Intelligence-Enabled Descriptive Flexfield

When you create business components for a business intelligence-enabled descriptive flexfield, the business component modeler recognizes the business intelligence-enabled setting. A view object that is flattened for Oracle Business Intelligence is generated alongside the standard descriptive flexfield polymorphic view object. You must also slightly modify the process of creating descriptive flexfield view links and application modules.

Before you begin:

1. Enable the flexfield and the desired segments for Oracle Business Intelligence as described in How to Enable a Descriptive Flexfield for .

2. If you have defined trees on any of the value sets that are referenced by the flexfield, ensure that the flattened tree view objects are already in your project. Otherwise, the Create Flexfield Business Components wizard that you use to create the flexfield business components will report the missing view objects as errors.

   For more information about flattened tree view objects, see About Designing a Column-Flattened View Object for Oracle Business Intelligence.

To produce a business intelligence-enabled flattened descriptive flexfield model:

1. Create descriptive flexfield business components as described in Creating Descriptive Flexfield Business Components.

   For a flexfield that is business intelligence-enabled, the Create Flexfield Business Components wizard generates a business intelligence-specific view object and other business components under a directory called analytics in the package root directory. These are generated in addition to the standard descriptive flexfield view object.

2. Create a view link using the procedure described in Creating Descriptive Flexfield View Links. Keep the following in mind:

   • The master view object that you create with the standard wizard can be the same master view object that you create for the core descriptive flexfield model.

   • Create the view link from the master view object to the business intelligence-enabled flexfield base view object. The business intelligence-enabled flexfield is distinguished from the core flexfield by the prefix "BI:" as shown in Figure 23-26.

     Figure 23-26 Create Flexfield View Link Wizard — View Objects Page

     

3. Create an application module for use with Oracle Business Intelligence as described in Adding a Descriptive Flexfield View Object to the Application Module. Make the following changes:

   1. On the Data Model page of the Create Application Module wizard, when you create an instance of the master view object, there is no need for a child view object.

   2. On the Application Modules page of the wizard, add an instance of the descriptive flexfield Oracle Business Intelligence application module as a nested instance of this application module. You can identify the Oracle Business Intelligence application module by the analytics subpackage under the package root.

   Note:

   If you already have a product Oracle Business Intelligence application module, you may use it.

4. Define the custom properties required to link the master view object instance to the default view instance inside the nested flexfield Oracle Business Intelligence application module instance.

   This is done on the General tab of the nested business intelligence-enabled flexfield application module instance definition, as shown in Figure 23-27.

   Figure 23-27 Custom Properties for Business Intelligence-Enabled Application Module

   

   As you define the custom properties, keep the following points in mind:

   • The default view instance inside the business intelligence-enabled flexfield application module is typically called DefaultFlexViewUsage.

   • The custom property names should be formatted as BI_VIEW_LINK_ mypropertyname

   • The custom property values must be formatted as source_viewobjectinstance_name , viewlink_definition_name , destination_viewobjectinstance_name .

   • Use the fully qualified view object instance names for the source view object and destination view object, and the fully qualified package name for the view link definition.

   • Business intelligence joins between the view object instances that you specify in different application modules are created while importing them from Oracle ADF if custom properties are defined on the application module.

23.14 Publish Descriptive Flexfields as Web Services

You can make access to a descriptive flexfield available through web services, which will enable you to create, retrieve, update and delete operations on the flexfield data rows. You accomplish this by exposing utility methods in the product application module to access flexfield service data objects.

Utility methods for flexfield service data objects are helpful to the customers because the identifiers that are used in flexfield services are generally not the same as those in the flexfield definition, such as the customer-defined segment codes and context codes. For example, the name of the service data object for the customer-defined context "Product Type" might be called "CasesDFFProduct_Type." These utility methods help customers quickly identify a service data object or a property of the object by the identifiers with which the customers are familiar.

When you generate a flexfield business component, the descriptive flexfield business components and other artifacts are developed based on the information in the flexfield metadata. As illustrated in Figure 23-8, a base view object is created for the context and global segments. If any contexts have been configured, subtype view objects are generated for each configured context.

The example in Figure 23-28 shows a Business Component Browser view of a descriptive flexfield.

Figure 23-28 Business Component Browser View of a Descriptive Flexfield

To complete the development process to publish descriptive flexfields as web services:

1. Expose the descriptive flexfield as a web service.

2. Test the web service.

23.14.1 How to Expose a Descriptive Flexfield as a Web Service

To make available web service access to a descriptive flexfield, you must complete the following steps:

1. Service-enable the master view object.

2. Expose the application module as a web service.

3. Expose the operations on the master view object.

4. Add utility methods for the flexfield to the product application module. These utility methods, which are exposed to client applications, provide access to information from the FlexfieldSdoSupport object, which is not exposed to clients.

You can then deploy the service and run Java client programs to test the service as described in How to Test the Web Service.

For more information about service-enabling an application module, see Integrating Service-Enabled Application Modules in Developing Fusion Web Applications with Oracle Application Development Framework .

Before you begin:

1. Create a flexfield business component for the flexfield's usage as described in How to Create Descriptive Flexfield Business Components.

   Note:

   When you generate a flexfield business component, the Create Descriptive Flexfield Business Components wizard automatically service-enables the business component by generating a Service Data Object (SDO) for the base view object and for every subtype view object.

2. Create a flexfield view link between the master view object, which contains only nonflexfield attributes, and the flexfield business component for the flexfield usage as described in How to Create Descriptive Flexfield View Links.

3. Nest the descriptive flexfield application module instance in the product application module as described in How to Nest the Descriptive Flexfield Application Module Instance in the Application Module.

4. Add the view object instance to the application module as described in How to Add a Descriptive Flexfield View Object Instance to the Application Module.

To expose a descriptive flexfield as a web service:

1. In the Application Navigator, open the view link between the master view object and the flexfield base view object.

2. In the overview editor, expand the Custom Properties section and add a SERVICE_PROCESS_CHILDREN property set to true, if one does not already exist.

3. Open the master view object, which is the view object that contains only the nonflexfield attributes.

4. In the overview editor click the Java navigation tab.

5. In the Java Classes section, click the Edit icon to generate and configure Java implementation classes.

6. In the Select Java Options dialog, select Generate Service Data Object Class, as shown in Figure 23-29.

   Figure 23-29 Generating a Service Data Object Class for the Master View Object

   

7. Click OK.

8. From the Application Navigator, open the product application module.

9. In the overview editor, click the Web Service navigation tab.

10. If the Add icon is enabled, complete the following steps to service-enable the application module and expose the master view object operations:

    1. Click the Add icon to enable the application to support the service interface.

    2. In the Create Service Interface wizard, click Next three times to go to the Service View Instances page.

    3. Move the view instance for the master view object to the Selected list.

    4. Select the master view object from the Selected list as shown in Figure 23-30, select all the operations in the Basic Operations list, and click OK.

       Figure 23-30 Selecting Master View Object Instances to Expose

       

    5. Click Finish.

11. If the Add icon is disabled, the application is already service enabled. Complete the following steps to expose the master view object operations:

    1. In the Service Interface View Instances section, click the Edit icon.

    2. Move the view instance for the master view object to the Selected list.

    3. Select the master view object from the Selected list as shown in Figure 23-30, select all the operations in the Basic Operations list, and click OK.

12. Expand the Generated Files for Service Interface section, and make a note of the name of the remote server class for the product application module. This is the class that has a name ending with ServiceImpl.java.

13. In the overview editor for the product application module, click the Java navigation tab and click the link for the Application Module Class.

14. Add the utility methods for the flexfield service data objects to the product application module. Include methods that return the namespace and name of the service data object for a given context. Optionally, include methods that return the path of an attribute that is associated with a given segment in the service data object. Use self-explanatory names that reflect the name of the flexfield and what is returned. Example 23-11 shows example utility methods for the CasesDFF flexfield. Example 23-12 shows an example of the methods being invoked in a client application. The self-explanatory utility method names make it easy to understand the client code.

15. In the overview editor for the product application module, click the Web Service navigation tab and click the Edit icon in the Service Interface Custom Methods section.

16. In the Service Custom Methods dialog, move the newly added methods to the Selected list to make them available for clients and click OK.

    The application module's remote server implementation class will be modified to expose these methods.

Example 23-11 Utility Methods for Cases DFF Flexfield Service Data Object Support

// A private method to retrieve a FlexfieldSdoSupport object // from the flexfield application module.   private FlexfieldSdoSupport getCasesDFFSdoSupport(String contextValue) {     // Find the nested flexfield application module instance.     DFFApplicationModuleImpl am =         (DFFApplicationModuleImpl)findApplicationModule("CasesDFFAM1");     // If contextValue is null, the base type is returned.     return am.getSdoSupport(contextValue); }   // Gets the namespace and name of the service data object for a // given context value.  Note how the method name and argument // name are specific to CasesDFF.   public List<String> getCasesServiceNamespaceAndName(String productType) {     FlexfieldSdoSupport ss = getCasesDFFSdoSupport(productType);     if (ss == null) {         throw new JboException("ERROR: Unable to fetch SDO for context " +                          productType +                          ".\nACTION NEEDED: Contact your system administrator. " +                          "Ensure context " + productType +                          " exists and the CasesDFF descriptive flexfield" +                          " is deployed using Manage Descriptive Flexfields.");       }     return Arrays.asList(ss.getSdoNamespace(), ss.getSdoName()); }   // Gets the property path for "Product Type," which is the context // segment of CasesDFF.   public String getCasesProductTypeServicePropertyPath() {     FlexfieldSdoSupport ss = getCasesDFFSdoSupport(null);     if (ss == null) {        throw new JboException("ERROR: Unable to fetch SDO for context" +            ".\nACTION NEEDED: " +            "Contact your system administrator. " +             "Ensure that the CasesDFF descriptive " +            "flexfield is deployed using Manage Descriptive Flexfields.");     }     return ss.getDiscriminatorSdoPath(); }   // Gets the property paths for a list of segments specific to a // product type.   public List<String> getCasesServicePropertyPaths(String productType,                                                  List<String> segmentCodes) {     FlexfieldSdoSupport ss = getCasesDFFSdoSupport(productType);     if (ss == null) {         throw new JboException("ERROR: Unable to fetch SDO for context " +                          productType +                          ".\nACTION NEEDED: Contact your system administrator. " +                          "Ensure context " + productType +                          " exists and the CasesDFF descriptive flexfield is " +                          "deployed using Manage Descriptive Flexfields.");       }     List<String> r = new ArrayList<String>(segmentCodes.size());     for (String segmentCode : segmentCodes) {         r.add(ss.getSegmentSdoPath(segmentCode));     }     return r; }                

Example 23-12 Client Application for Updating CasesDFF in a CaseList Row

// Obtain the service definition for product type "Office Chair." List<String> chairObjInfo=   caseListService.getCasesServiceNamespaceAndName("Office Chair");   // Create a service data object for "Office Chair." DataObject chairObj = dataFactory.create(chairObjInfo.get(0),                                          chairObjInfo.get(1));   // Set the product type, so the product type matches the object type chairObj.set(caseListService.getCasesProductTypeServicePropertyPath(),              "Office Chair");   // Obtain the element names of the segments and set the values. List<String> segmentPaths =   caseListService.getCasesServicePropertyPaths("Office Chair",                                                Arrays.asList("Broken Part"));   // Update the segment "Broken Part." chairObj.set(segmentPaths.get(0), "Chair Back");                

23.14.2 How to Test the Web Service

You can test the service by adding StringRefAddr elements to the Reference element for the product application module's service to the connections.xml file, deploying and manually testing the service, and optionally creating and running Java client programs to test the service.

Before you begin:

• Expose the descriptive flexfield as a web service as described in How to Expose a Descriptive Flexfield as a Web Service.

• Ensure that the BC4J Service Client and BC4J Service Runtime libraries are included in your project.

To test the web service:

1. Expand Application Resources, expand Descriptors, expand ADF Meta-INF, and open the connections.xml file.
2. Locate the Reference element for the product application module's service (DFF1MasterApplicationModuleService in this example).
3. Add the StringRefAddr elements that are shown in bold in Example 23-13 to the Reference element for the product application module's service. Modify the host and port number in the jndiProviderURL entry to point to Oracle WebLogic Server. The port number is typically 7101.
4. Run the remote server class for the product application module to deploy the service to Integrated WebLogic Server and to manually test the web service.
5. Optionally, create and run Java client programs to test invoking the web service:

   The following examples demonstrate how to write programs to test the web service.

   • Example 23-17 shows how to get a data row. The XML payload output of this program is shown in Example 23-18.

   • Example 23-19 shows how to create a new data row.

   • Example 23-20 shows how to update an existing data row.

   Note:

   You must provide the flexfield's xsi:subtype value in the payloads that are sent to the service. If you do not provide the xsi:subtype value, the attributes for that subtype are ignored, and will not be created or updated.

Example 23-13 StringRefAddr Elements to Add to Service Reference in connections.xml

<Reference name="{http://xmlns.oracle.com/oracle/apps/fnd/applcore/flex/test/dff1/model/}DFF1MasterApplicationModuleService" className="oracle.jbo.client.svc.Service" xmlns="">    <Factory className="oracle.jbo.client.svc.ServiceFactory"/>    <RefAddresses>       <StringRefAddr addrType="serviceInterfaceName">          <Contents>oracle.apps.fnd.applcore.flex.test.dff1.model.DFF1MasterApplicationModuleService</Contents>       </StringRefAddr>       <StringRefAddr addrType="serviceEndpointProvider">          <Contents>ADFBC</Contents>       </StringRefAddr>       <StringRefAddr addrType="jndiName">          <Contents>DFF1MasterApplicationModuleServiceBean#oracle.apps.fnd.applcore.flex.test.dff1.model.DFF1MasterApplicationModuleService</Contents>       </StringRefAddr>       <StringRefAddr addrType="serviceSchemaName">          <Contents>DFF1MasterApplicationModuleService.xsd</Contents>       </StringRefAddr>       <StringRefAddr addrType="serviceSchemaLocation">          <Contents>oracle/apps/fnd/applcore/flex/test/dff1/model/</Contents>       </StringRefAddr>                                      <StringRefAddr addrType="jndiFactoryInitial">                                      <Contents>weblogic.jndi.WLInitialContextFactory</Contents>                                      </StringRefAddr>                                      <StringRefAddr addrType="jndiProviderURL">                  <Contents>t3://                  localhost:port_number                  </Contents>                                      </StringRefAddr>                                      <StringRefAddr addrType="jndiSecurityPrincipal">                                      <Contents>weblogic</Contents>                                      </StringRefAddr>                                      <StringRefAddr addrType="jndiSecurityCredentials">                                      <Contents>weblogic1</Contents>                                      </StringRefAddr>                  </RefAddresses> </Reference>                

Example 23-14 Example Get Payload Input for Fusion Service Tester Utility

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">     <soap:Body>         <ns1:getCaseList1  xmlns:ns1="http://xmlns.oracle.com/apps/fnd/applcore/crmdemo/types/">             <ns1:id>100128</ns1:id>         </ns1:getCaseList1>     </soap:Body> </soap:Envelope>                

Example 23-15 Example Create Payload Input for Fusion Service Tester Utility

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">          <soap:Body>         <ns1:createCaseList1 xmlns:ns1="http://xmlns.oracle.com/apps/fnd/applcore/crmdemo/types/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">             <ns1:caseList1 xmlns:ns0="http://xmlns.oracle.com/apps/fnd/applcore/crmdemo/">                 <ns0:Id>99910</ns0:Id>                 <ns0:TypeName>Service Request</ns0:TypeName>                 <ns0:CustomerName>A Corporation</ns0:CustomerName>                 <ns0:StatusName>Priority</ns0:StatusName>                 <ns0:StatusIconClass>DemoStatusPriority</ns0:StatusIconClass>                 <ns0:StatusDate>2012-12-10</ns0:StatusDate>                 <ns0:DateInitiated>2011-12-28</ns0:DateInitiated>                 <ns0:LastModifiedDate>2012-12-10</ns0:LastModifiedDate>                 <ns0:ProblemDescription>Customer's K3000 Industrial Anvil from                                         A Company is broken. They                                         need help in fixing it.                 </ns0:ProblemDescription>                 <ns0:AssignedUserFirstName>Myfirst</ns0:AssignedUserFirstName>                 <ns0:AssignedUserLastName>Mylast</ns0:AssignedUserLastName>                 <ns0:AssignedUserMiddleInitial>M</ns0:AssignedUserMiddleInitial>                 <ns0:AssignedUserFullName>Myfirst M. Mylast                 </ns0:AssignedUserFullName>                 <ns0:AssignedUserDate>2012-12-10</ns0:AssignedUserDate>                 <ns0:CustomerId>10035</ns0:CustomerId>                 <ns0:TypeId>47</ns0:TypeId>                 <ns0:StatusIdIndex>2</ns0:StatusIdIndex>                 <ns0:AssignedUserIdIndex>10000</ns0:AssignedUserIdIndex>                 <ns0:StatusId>2</ns0:StatusId>                 <ns0:AssignedUserId>10000</ns0:AssignedUserId>                 <ns0:Ccid>21</ns0:Ccid>                 <ns0:Sin>12207</ns0:Sin>                 <ns0:CustomerProductId>36</ns0:CustomerProductId>                 <ns0:AttachmentEntityName>FND_CRM_CASE_LIST                 </ns0:AttachmentEntityName>                 <ns0:caseListServiceId xsi:nil="true"/>                 <ns0:TypeId1>47</ns0:TypeId1>                 <ns0:CustomerProductId1>36</ns0:CustomerProductId1>                 <ns0:CustomerId1>10035</ns0:CustomerId1>                 <ns0:FndCrmCasesDFFVLA  xmlns:ns3="http://xmlns.oracle.com/apps/fnd/applcore/crmdemo/flex/cases/"                     xsi:type="ns3:CasesDFFIndustrial__Anvil">                     <ns3:Id>99910</ns3:Id>                     <ns3:_CUSTOMER_EMAIL>myemail@example.com                     </ns3:_CUSTOMER_EMAIL>                     <ns3:_RESOLUTION_DATE xsi:nil="true"/>                     <ns3:_ESCALATION_LEVEL>3</ns3:_ESCALATION_LEVEL>                     <ns3:__FLEX_Context>Industrial Anvil</ns3:__FLEX_Context>                     <ns3:_FLEX_NumOfSegments>4</ns3:_FLEX_NumOfSegments>                     <ns3:_WEIGHT>60</ns3:_WEIGHT>                 </ns0:FndCrmCasesDFFVLA>             </ns1:caseList1>         </ns1:createCaseList1>     </soap:Body> </soap:Envelope>                

Example 23-16 Example Update Payload Input for Fusion Service Tester Utility

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">     <soap:Body>         <ns1:updateCaseList1 xmlns:ns1="http://xmlns.oracle.com/apps/fnd/applcore/crmdemo/types/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">             <ns1:caseList1 xmlns:ns0="http://xmlns.oracle.com/apps/fnd/applcore/crmdemo/">                 <ns0:Id>99910</ns0:Id>                 <ns0:TypeName>Service Request</ns0:TypeName>                 <ns0:CustomerName>A Corporation</ns0:CustomerName>                 <ns0:StatusName>Priority</ns0:StatusName>                 <ns0:StatusIconClass>DemoStatusPriority</ns0:StatusIconClass>                 <ns0:StatusDate>2012-12-10</ns0:StatusDate>                 <ns0:DateInitiated>2011-12-28</ns0:DateInitiated>                 <ns0:LastModifiedDate>2012-12-10</ns0:LastModifiedDate>                 <ns0:ProblemDescription>Customer's K3000 Industrial Anvil from                                         A Company is broken. They                                         need help in fixing it.                 </ns0:ProblemDescription>                 <ns0:AssignedUserFirstName>Myfirst</ns0:AssignedUserFirstName>                 <ns0:AssignedUserLastName>Mylast</ns0:AssignedUserLastName>                 <ns0:AssignedUserMiddleInitial>M</ns0:AssignedUserMiddleInitial>                 <ns0:AssignedUserFullName>Myfirst M. Mylast                 </ns0:AssignedUserFullName>                 <ns0:AssignedUserDate>2012-12-10</ns0:AssignedUserDate>                 <ns0:CustomerId>10035</ns0:CustomerId>                 <ns0:TypeId>47</ns0:TypeId>                 <ns0:StatusIdIndex>2</ns0:StatusIdIndex>                 <ns0:AssignedUserIdIndex>10000</ns0:AssignedUserIdIndex>                 <ns0:StatusId>2</ns0:StatusId>                 <ns0:AssignedUserId>10000</ns0:AssignedUserId>                 <ns0:Ccid>21</ns0:Ccid>                 <ns0:Sin>12207</ns0:Sin>                 <ns0:CustomerProductId>36</ns0:CustomerProductId>                 <ns0:AttachmentEntityName>FND_CRM_CASE_LIST                 </ns0:AttachmentEntityName>                 <ns0:caseListServiceId xsi:nil="true"/>                 <ns0:TypeId1>47</ns0:TypeId1>                 <ns0:CustomerProductId1>36</ns0:CustomerProductId1>                 <ns0:CustomerId1>10035</ns0:CustomerId1>                 <ns0:FndCrmCasesDFFVLA xmlns:ns3="http://xmlns.oracle.com/apps/fnd/applcore/crmdemo/flex/cases/"                     xsi:type="ns3:CasesDFFRoller__Skate">                     <ns3:Id>99910</ns3:Id>                     <ns3:_CUSTOMER_EMAIL>myemail@example.com</ns3:_CUSTOMER_EMAIL>                     <ns3:_RESOLUTION_DATE xsi:nil="true"/>                     <ns3:_ESCALATION_LEVEL>0</ns3:_ESCALATION_LEVEL>                     <ns3:__FLEX_Context>Roller Skate</ns3:__FLEX_Context>                     <ns3:_FLEX_NumOfSegments>4</ns3:_FLEX_NumOfSegments>                     <ns3:_BROKEN_PART>Wheel Casing</ns3:_BROKEN_PART>                 </ns0:FndCrmCasesDFFVLA>             </ns1:caseList1>         </ns1:updateCaseList1>     </soap:Body> </soap:Envelope>                

Example 23-17 Web Service Get Operation

package oracle.apps.fnd.applcore.flex.test.dff1.model.test;   import ...   public class DFFTester {     private static final String PK1 = "MY_PRIMARY_KEY";     public DFFTester() {         super();     }    public void getFKRowGivenKey(){     try     {       DFF1MasterApplicationModuleService dff1Service =         (DFF1MasterApplicationModuleService)         ServiceFactory.getServiceProxy(         DFF1MasterApplicationModuleService.NAME);         List<String> dff1Info = dff1Service.getMyFlexfieldSdoNamespaceAndName(null);       System.out.println(dff1Info);         final String contextValue = "MY_CONTEXT_VALUE";       List<String> dffInfo2 =           dff1Service.getMyFlexfieldSdoNamespaceAndName(contextValue);       System.out.println(dffInfo2);                       MasterDff masterVOSDO = dff1Service.getMasterDff1(PK1);       DataObject dataObject = (DataObject) masterVOSDO;       String uri = dataObject.getType().getURI();       XMLHelper xmlhelper = ServiceFactory.getXMLHelper(dff1Service);       String xml = xmlhelper.save(dataObject, uri, "MasterDff");       System.out.println(xml);       }         }catch(Exception e){             e.printStackTrace();         }     }       public static void main(String args[]){           DFFTester dfftester =new DFFTester();            dfftester.getFKRowGivenKey();     } }                

Example 23-18 Example XML Payload Output of Web Service Get Operation

<?xml version="1.0" encoding="UTF-8"?> <ns2:MasterDff xmlns:ns2="http://xmlns.oracle.com/apps/fnd/applcore/flex/test/dff1/model/" xmlns:ns1="http://xmlns.oracle.com/apps/fnd/applcore/flex/test/dff1/flex/dff1/" xmlns:ns0="http://xmlns.oracle.com/adf/svc/types/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:MasterDff"> <ns2:CreatedBy>0</ns2:CreatedBy> <ns2:CreationDate>2009-12-03T23:39:25.0-08:00</ns2:CreationDate> <ns2:LastUpdateDate>2009-12-03T23:39:25.0-08:00</ns2:LastUpdateDate> <ns2:LastUpdateLogin>0</ns2:LastUpdateLogin> <ns2:LastUpdatedBy>0</ns2:LastUpdatedBy> <ns2:PrimaryKeyCode>VS_IND_COC_DEP_DAT_ON_DAT05</ns2:PrimaryKeyCode> <ns2:ProductContext xsi:nil="true"/> <ns2:ProductDate xsi:nil="true"/> <ns2:ProductNumber xsi:nil="true"/> <ns2:ProductVarchar2 xsi:nil="true"/> <ns2:dff1 xsi:type="ns1:Dff1VS_5FIND_5FCOC_5FDEP_5FDAT_5FON_5FDAT"> <ns1:PrimaryKeyCode>VS_IND_COC_DEP_DAT_ON_DAT05</ns1:PrimaryKeyCode> <ns1:_FLEX_ValidationDate>2009-12-03</ns1:_FLEX_ValidationDate> <ns1:_GlobalSegment1>05</ns1:_GlobalSegment1> <ns1:_GlobalSegment2>Value05</ns1:_GlobalSegment2> <ns1:_GLOBAL_STATE_ID_NUM xsi:nil="true"/> <ns1:_GLOBAL_STATE_ID_NUM_Display xsi:nil="true"/> <ns1:_FLEX_Context>VS_IND_COC_DEP_DAT_ON_DAT</ns1:_FLEX_Context> <ns1:_FLEX_NumOfSegments>5</ns1:_FLEX_NumOfSegments> <ns1:_State>RI</ns1:_State> <ns1:_State_Holiday>2007-08-12</ns1:_State_Holiday> </ns2:dff1> </ns2:MasterDff>                

Example 23-19 Web Service Create Operation

...     public void createMasterDffRow() {         try {               DFF1MasterApplicationModuleService dff1Service =                 (DFF1MasterApplicationModuleService)                 ServiceFactory.getServiceProxy(                 DFF1MasterApplicationModuleService.NAME);             DataFactory dataFactory =                 ServiceFactory.getDataFactory(dff1Service);             MasterDffImpl dffMaster =                 (MasterDffImpl)dataFactory.create(MasterDff.class);             dffMaster.setPrimaryKeyCode(PK1);               final String contextValue = "MY_CONTEXT";             List<String> dffInfo =                 dff1Service.getMyFlexfieldSdoNamespaceAndName(contextValue);             System.out.println(dffInfo);             DataObject dffSubType =                 dataFactory.create(dffInfo.get(0), dffInfo.get(1));             System.out.println(dff1Service.getMyFlexfieldTypeSdoPath());             dffSubType.set(dff1Service.getMyFlexfieldTypeSdoPath(), contextValue);             dffSubType.set(dff1Service.getMyFlexfieldSegmentSdoPaths(contextValue,               Arrays.asList("GLOBAL_STATE_ID_NUM")).get(0),                            new BigDecimal(100));             dffSubType.set(dff1Service.getMyFlexfieldSegmentSdoPaths(contextValue,               Arrays.asList("Date_On_Date")).get(0),                            java.sql.Date.valueOf("2011-04-18"));             dffMaster.setDff1(dffSubType);             dff1Service.createMasterDff1(dffMaster);                 MasterDffImpl masterVOSDO =                 (MasterDffImpl)dff1Service.getMasterDff1(PK1);             String updatedXML =                 DFFTester.extractXMLFromDataObject(dff1Service, masterVOSDO);             System.out.println("<<<--------Updated XML output-------------->");             System.out.println("");             System.out.println(updatedXML);           } catch (Exception e) {             e.printStackTrace();         }     } ...                

Example 23-20 Web Service Update Operation

...     public void updateMasterDffRow() {         try {               DFF1MasterApplicationModuleService dff1Service =                 (DFF1MasterApplicationModuleService)                 ServiceFactory.getServiceProxy(                 DFF1MasterApplicationModuleService.NAME);             DataFactory dataFactory =                 ServiceFactory.getDataFactory(dff1Service);               MasterDffImpl dffMaster =                 (MasterDffImpl)dff1Service.getMasterDff1(PK1);             XMLHelper xmlhelper = ServiceFactory.getXMLHelper(dff1Service);             String uri = dffMaster.getType().getURI();             String xml = xmlhelper.save(dffMaster, uri, "MasterDff");             System.out.println(xml);                 Object dffObject = dffMaster.getDff1();             System.out.println("Dff Object Name->" +                                dffObject.getClass().getName());               final String contextValue = "MY_CONTEXT";             List<String> dffInfo =                 dff1Service.getMyFlexfieldSdoNamespaceAndName(contextValue);             System.out.println(dffInfo);             DataObject dffSubType =                 dataFactory.create(dffInfo.get(0), dffInfo.get(1));             System.out.println(dff1Service.getMyFlexfieldTypeSdoPath());             dffSubType.set(dff1Service.getMyFlexfieldTypeSdoPath(), contextValue);               dffSubType.set(dff1Service.getMyFlexfieldSegmentSdoPaths(contextValue,               Arrays.asList("GlobalSegment1")).get(0),                            new BigDecimal(02));             dffSubType.set(dff1Service.getMyFlexfieldSegmentSdoPaths(contextValue,               Arrays.asList("P6_S0_On_Number")).get(0),                            new BigDecimal(123));             dffMaster.setDff1(dffSubType);             dff1Service.updateMasterDff1(dffMaster);                 dffMaster = (MasterDffImpl)dff1Service.getMasterDff1(PK1);             String updatedXML =                 DFFTester.extractXMLFromDataObject(dff1Service, dffMaster);             System.out.println("<<<--------Updated XML output-------------->");             System.out.println("");             System.out.println(updatedXML);           } catch (Exception e) {             e.printStackTrace();         }     } ...                

23.15 Accessing Descriptive Flexfields from an ADF Desktop Integration Excel Workbook

ADF Desktop Integration makes it possible to combine desktop productivity applications with Oracle Fusion Applications, so you can use a program like Microsoft Excel as an interface to access application data.

Using ADF Desktop Integration, you can incorporate descriptive flexfields into an integrated Excel workbook, so you can work with the flexfield data from within the workbook.

The Oracle Fusion Middleware Developing Applications with Oracle ADF Desktop Integration guide provides most of the information you need to complete the required activities, including the following:

• Preparing your development environment for desktop integration.

• Creating a page definition file that will expose the Oracle ADF bindings for use in Excel.

• Creating an Excel workbook to integrate with the descriptive flexfield.

• Preparing your Excel workbook to access the column containing the flexfield.

• Incorporating a descriptive flexfield as a dynamic component or a single cell on a worksheet in the workbook.

The Oracle Fusion Middleware Developing Applications with Oracle ADF Desktop Integration guide does not make explicit reference to flexfields. In addition to the standard implementation steps covered in that guide, you must modify your implementation to accommodate flexfields.

There are two ways to access a descriptive flexfield in Excel:

• Using a dynamic column in an ADF Desktop Integration Table.

  A web page in a popup dialog can be associated with a dynamic column, enabling end users to pick flexfield segment values. Alternatively, users can enter values directly into the segment fields. No custom code is required in either case.

  This is the most typical scenario. Each descriptive flexfield segment is displayed as a distinct column in the ADF Desktop Integration Table.

• Using a static column in a popup dialog associated with a single cell. Use this approach for either of the following reasons:

  • The descriptive flexfield is exposed in an ADF Desktop Integration Table, is context sensitive, and the context changes from row to row. A static column is required in this case.

  • You do not want descriptive flexfield segments to occupy too much space in the worksheet.

  In addition to using the popup dialog, end users can enter values directly into the segment field, with the values separated by an appropriate delimiter that you specify.

  Note:

  A static column is any column for which the DynamicColumn property is set to False.

  Individual flexfield segments do not appear in the worksheet. Instead, ADF Desktop Integration invokes a separate JSPX page on which the flexfield will be visible. You can use this scenario with an ADF Desktop Integration Form, or either table type.

The descriptive flexfield's segments are part of your database table, so the flexfield is generated against the same entity object on which your worksheet view object is based.

To complete the process for accessing descriptive flexfields from an ADF Desktop Integration Excel workbook:

1. Configure ADF Desktop Integration with either a dynamic or static column descriptive flexfield.

2. If using a dynamic column descriptive flexfield where the end user can control the context value, modify the application to update the descriptive flexfield structure whenever user-initiated context value changes occur in the dynamic column descriptive flexfield.

3. Create a custom method to process updates or inserts for descriptive flexfield data row and add code to invoke the method.

23.15.1 How to Configure ADF Desktop Integration with a Dynamic Column Descriptive Flexfield

When you configure the ADF Desktop Integration Table, make the following changes:

• Add the ADF Desktop Integration Model API library to your data model project.

• In your page definition for the worksheet, add the descriptive flexfield that you want to access to the master worksheet view object as a child node. Do not add any display attribute to the child node that expands as a dynamic column in the worksheet.

  For more information about how to create a page definition file for an ADF Desktop Integration project, see the Working with Page Definition Files for an Integrated Excel Workbook section of the Developing Applications with Oracle ADF Desktop Integration .

• To make the descriptive flexfield column of the ADF Desktop IntegrationTable dynamic, set the DynamicColumn property in the TableColumn array of the ADF Desktop Integration Table to True. A dynamic column in the TableColumn array is a column that is bound to a tree binding or tree node binding whose attribute names are not known at design time. A dynamic column can expand to more than a single worksheet column at runtime.

  For more information about the binding syntax for dynamic columns, see the Adding a Dynamic Column to Your ADF Table Component section of the Developing Applications with Oracle ADF Desktop Integration .

• For the table's UpdateComponent and InsertComponent properties, specify one of the following as the subcomponent to use:

  • Inputtext

  • OutputText

  • ModelDrivenColumnComponent

• For the subcomponent's Value property, access the Expression Builder, expand the Bindings node and your tree binding for the table, and select the flexfield node.

• For the subcomponent's Label property, access the Expression Builder, expand the Bindings node and your tree binding for the table, and select the flexfield node.

23.15.2 How to Handle User-Initiated Context Value Changes in a Dynamic Column Descriptive Flexfield

ADF Desktop Integration requires that to use a dynamic column implementation, the structure of the descriptive flexfield must remain constant for all rows in a given result set. However, each time a new result set is downloaded into the table, the context value (and thus the structure) can be changed.

If the context value is set globally for the end user of the workbook, changes are not an issue. However, if the user can control the context value (for example, using a list of values (LOV) in a header form), your application must be able to respond appropriately to update the descriptive flexfield structure.

After the end user specifies a context value, you must invoke the worksheet UpSync method to get the new value into the model layer. Then you can use the ADF Desktop Integration Table Download method to get fresh data with the new descriptive flexfield structure.

Note:

For an insert-only table, the Download method is undesirable. For these cases, use either the ADF Desktop Integration Table DownloadForInsert method or the Initialize method to enable the ADF Desktop Integration Table to reconfigure to accommodate the new flexfield structure.

23.15.3 How to Configure ADF Desktop Integration with a Static Column Descriptive Flexfield

If the structure of your descriptive flexfield varies from row to row in a given result set, you cannot implement the flexfield as a dynamic column — it will produce errors. You must use a static column with a popup dialog.

Note:

If a specific dialog title cannot be provided because the configuration of the flexfield will not be known until implementation, use "Additional Information" for the title, which is the standard generic label in such a case for Oracle Fusion Applications.

ADF Desktop Integration supports descriptive flexfields by using tree bindings in an ADF Desktop Integration Table. If you desire, the table can be configured to be read-only.

Note:

A descriptive flexfield appears as a node in the tree binding at design time. Because flexfields are built up dynamically at runtime, you will not see any attributes under the flexfield node in the page definition, but the node itself is present.

When you configure the popup dialog, make the following changes:

• You can use the column's action set properties to make the descriptive flexfield web page available for editing. Include the attributes used in the web page in the table's cached attributes unless the row will be committed immediately.

• You must choose a fixed attribute (a descriptive flexfield global segment attribute) to represent the flexfield in the worksheet. Add a Dialog action to the DoubleClickActionSet component action of an InputText or OutputText component, then connect the Dialog action to JSPX page that will display the descriptive flexfield.

  For more information about how to create a page definition file for an ADF Desktop Integration Table project, see the Working with Page Definition Files for an Integrated Excel Workbook section of the Developing Applications with Oracle ADF Desktop Integration .

For static display of a descriptive flexfield in an ADF Desktop Integration workbook, you must create an updatable transient attribute in the view object on which the ADF Desktop Integration Table is based. This transient attribute will hold the concatenated value of the descriptive flexfield segments, separated by a delimiter. If one purpose of the worksheet is to display existing data from the database, the transient attribute should be populated using custom application module methods upon returning from a popup dialog or opening the worksheet.

23.15.4 How to Handle Updating or Inserting of a Descriptive Flexfield Data Row

To handle updating or inserting of a data row containing a descriptive flexfield in an ADF Desktop Integration Table, you call a custom application module method that contains appropriate code, as follows:

• To update an existing row, add your code to the UpdateRowActionId property of the table.

• To insert a new row, add your code to the InsertAfterRowActionId property of the table.

The context value should be set before calling the application module method, which gets called in the doubleclickactionset component action of the table's UpdateComponent or InsertComponent properties. This is applicable for both dynamic column and static column display of descriptive flexfields. Setting the context value appropriately is important because this controls the structure of the flexfield.

The following examples demonstrate the code needed to accomplish these tasks. Example 23-21 and Example 23-22 apply to an ADF Desktop Integration implementation with the descriptive flexfield exposed as a static column. Example 23-23 presents the isSegmentDisplayable() method that is used in the other two examples.

Example 23-21 Updating or Inserting a Row with a Static Column Descriptive Flexfield

//Retrieve your worksheet view object                  myworksheet_VOImpl                  srcVO =                  myVO                  //Retrieve the current row from your view object.  //That is the row that is being processed by ADF Desktop Integration.                  myworksheet_VO_Row_Impl                  srcRow =                  myworksheet_VO_Row_Impl                  srcVO.getCurrentRow();    //This gives the transient attribute value from your worksheet.   Object dffAttributeValue = srcRow.getAttribute(mytransientattribute);    //Get the descriptive flexfield row based on the descriptive flexfield view accessor.   DFFViewRowImpl dffRow = (DFFViewRowImpl)srcRow.getAttribute(mydff_viewaccessor);    //Check if the single cell value is null.  if (dffAttributeValue != null && !("").equals(dffAttributeValue)) {       //Getting DFF metadata information       FlexfieldViewDefImpl dffImpl =           (FlexfieldViewDefImpl)dffRow.getFlexfieldViewDef();       String delim = dffImpl.getDelimiter();       //Parse the DFF string into tokens       StringTokenizer token =           new StringTokenizer(dffAttributeValue.toString(), delim);         while (token.hasMoreTokens()) {           prjValues.add(token.nextToken());       }   }   //Get the descriptive flexfield segment information.   ListAttributeDef                  listSeg =       dffRow.getFlexfieldViewDef().getFlexfieldAttributes();     Iterator listSegIterator = listSeg.iterator();   AttributeDef seg = null;   ListString                  segDisplay = new ArrayListString();   while (listSegIterator.hasNext()) {       seg = (AttributeDef)listSegIterator.next();       if (isSegmentDisplayable(seg, dffRow)) {           segDisplay.add(seg.getName());       }   }     //Get the size of the segment.   int segValueSize=0;   if (dffAttributeValue != null && !("").equals(dffAttributeValue))       segValueSize = prjValues.size();   else       segValueSize = segDisplay.size();     //This check is required to handle a context dependent DFF case.   //If the context is changed before uploading, do not proceed.   if (segValueSize < prjValues.size())      return;   if (segDisplay.size()==0)      return;     for (int i = 0; i < segValueSize; i++) {      if (dffAttributeValue != null && !("").equals(dffAttributeValue)) {           if (prjValues.get(i) != null && !prjValues.get(i).equals(" ")){               dffRow.setAttribute(segDisplay.get(i), prjValues.get(i));            } else {               dffRow.setAttribute(segDisplay.get(i), null);            }      } else {           dffRow.setAttribute(segDisplay.get(i), null);       }   }                

Example 23-22 Applying Modified Segment Values to a Cell in a Static Column Descriptive Flexfield

Add this code as an application module method that will be invoked by clicking the OK button of a popup dialog. This method can also be used to populate transient attribute values used for single cell display upon opening the worksheet, if the worksheet is intended to display existing records from the database.

//Retrieve the DFF row through the DFF view accessor.  DFFViewRowImpl dffRow =    (DFFViewRowImpl)row.getAttribute(   "DFF_viewaccessorattribute_from_worksheetVO");   //Get the delimiter information for your DFF.  FlexfieldViewDefImpl dffImpl =      (FlexfieldViewDefImpl)dffRow.getFlexfieldViewDef();  String delim = dffImpl.getDelimiter();   //Get the segment information for your DFF.  ListAttributeDef                  listSeg =      dffRow.getFlexfieldViewDef().getFlexfieldAttributes();    //Your DFF will have many segments, but not all of them will be used for display.  //This code loops through DFF segments and obtains the name and type  //of each displayable segment.  Iterator listSegIterator = listSeg.iterator();  AttributeDef seg = null;  Liststring                  segDisplay = new ArrayListstring();  Listinteger                  segDisplayType = new ArrayListinteger();    while (listSegIterator.hasNext()) {      seg = (AttributeDef)listSegIterator.next();       if (isSegmentDisplayable( seg,dffRow)) {                  segDisplay.add(seg.getName());                  segDisplayType.add(new Integer(seg.getSQLType()));              }    } int segDisplaySize = segDisplay.size(); StringBuffer segmentString = new StringBuffer();        //  This loop is constructing a string out of displayed segment values   //  with a delimiter in between each segment value.     //  If the segment type is date, remove the time from the date.   //  For the first segment (i=0), you need to handle it differently   //  to construct the string correctly.         for (int i = 0; i < segDisplaySize; i++) {             if (dffRow.getAttribute(segDisplay.get(i)) != null) {                 if (i == 0) {                     if (segDisplayType.get(i) == 91) {                         StringTokenizer stTime =                              new  StringTokenizer(dffRow.getAttribute(segDisplay.get(i)).toString(), " ");                           segmentString.append(stTime.nextToken());                     } else {                          segmentString.append(dffRow.getAttribute(segDisplay.get(i)));                     }                } else {                       segmentString.append(delim);                      if (segDisplayType.get(i) == 91) {                         if (dffRow.getAttribute(segDisplay.get(i)) != null) {                            StringTokenizer stTime =                                new  StringTokenizer(dffRow.getAttribute(segDisplay.get(i)).toString(), " ");                           segmentString.append(stTime.nextToken());                         } else {                            segmentString.append(                              dffRow.getAttribute(segDisplay.get(i)));                      }                  } else {                      segmentString.append(dffRow.getAttribute(segDisplay.get(i)));                  }                                        }              }else {                  if (i==0)                      segmentString.append(" ");                   else {                      segmentString.append(delim);                      segmentString.append(" ");                  }              }          }    row.setyour_transient_attribute(segmentString)                

Example 23-23 isSegmentDisplayable() Helper Method Used in the Previous Examples

The input parameters for this method are the segment attribute definition and the descriptive flexfield row.

public boolean isSegmentDisplayable(AttributeDef seg,                                        DFFViewRowImpl dffRow) {     if (seg.getProperty("FND_ACFF_DisplayAttributeName") == null) {         if (seg.getProperty(seg.getUIHelper().ATTRIBUTE_DISPLAY_HINT) ==null ||             !seg.getProperty(               seg.getUIHelper().ATTRIBUTE_DISPLAY_HINT).equals("Hide")) {                return true;           } else {                return false;         }     } else {         int attrIndex =             dffRow.getFlexfieldViewDef().getAttributeIndexOf(               seg.getProperty("FND_ACFF_DisplayAttributeName").toString());         AttributeDef displayAttrDef =             dffRow.getFlexfieldViewDef().getAttributeDef(attrIndex);         if (displayAttrDef.getProperty(           seg.getUIHelper().ATTRIBUTE_DISPLAY_HINT) == null ||             !displayAttrDef.getProperty(               seg.getUIHelper().ATTRIBUTE_DISPLAY_HINT).equals("Hide")) {                return true;         } else {                return false;         }     } }                

How To Use Descriptive Flexfield In Oracle Apps

Source: https://docs.oracle.com/applications/falcm12/OADEE/GUID-FCA838E1-D48C-43AB-8B5B-F746A52BA33D.htm

Posted by: harperwinfory49.blogspot.com

Share this post