| Oracle® Fusion Applications Developer's Guide 11g Release 1 (11.1.1.5) Part Number E15524-01 |
|
|
View PDF |
| Oracle® Fusion Applications Developer's Guide 11g Release 1 (11.1.1.5) Part Number E15524-01 |
|
|
View PDF |
This chapter discusses how to use descriptive flexfields to enable customers to add additional attributes to application business objects.
This chapter includes the following sections:
Section 22.3, "Creating Descriptive Flexfield Business Components"
Section 22.6, "Adding a Descriptive Flexfield View Object to the Application Module"
Section 22.7, "Adding Descriptive Flexfield UI Components to a Page"
Section 22.8, "Configuring Descriptive Flexfield UI Components"
Section 22.10, "Working with Descriptive Flexfield UI Programmatically"
Section 22.11, "Incorporating Descriptive Flexfields Into a Search Form"
Section 22.13, "Publishing Descriptive Flexfields as Web Services"
Section 22.14, "Accessing Descriptive Flexfields from an ADF Desktop Integration Excel Workbook"
Descriptive flexfields provide a way for customers to add custom attributes to entities, and to define validation and display properties for them. A descriptive flexfield is a logical grouping of attributes (segments) that are mapped to a set of extension columns, which are shipped as part of Oracle Fusion Applications tables. The attributes in the group are of two types: global segments and context-sensitive segments. 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. To learn more about global, context, and context-sensitive segments, see Chapter 21, "Getting Started with Flexfields."
You can define multiple usages for a descriptive flexfield. For example, you might have defined an address flexfield that the implementer may use to add attributes related to addresses. The implementer 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 customer only needs to configure the flexfield once.
To complete the development tasks for descriptive flexfields:
Create the extension columns to store the flexfield data, and then register the flexfield definition, usage, and parameter metadata.
Create descriptive flexfield business components.
See Section 22.3, "Creating 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.For more information, see Section 25.4, "Regenerating Flexfield Business Components Programmatically".
Create view links between the descriptive flexfield business components and your application's business components.
See Section 22.4, "Creating Descriptive Flexfield View Links".
Nest the descriptive flexfield application module instance in the application module.
Add a descriptive flexfield view object instance to the application module.
See Section 22.6, "Adding a Descriptive Flexfield View Object to the Application Module".
Add the descriptive flexfield usage to the appropriate application pages.
See Section 22.7, "Adding Descriptive Flexfield UI Components to a Page".
Configure the descriptive flexfield UI components.
See Section 22.8, "Configuring Descriptive Flexfield UI Components".
Load any necessary application seed data, such as error messages or lookup values.
After implementing a flexfield, you can define seed or test value sets for the flexfield, and you can create a model that you can use to test it. For more information, see Section 25.1.2, "How to Test Flexfields."
Once you have completed the flexfield development process and delivered your application, implementers 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. For information about planning and implementing flexfield configuration, such as defining attributes, labels, behavior, and associated value sets, see the "Using Flexfields for Custom Attributes" chapter in the Oracle Fusion Applications Extensibility Guide.
To make the Manage Descriptive Flexfields task flows available to application implementers, you register them with the Oracle Fusion Functional Setup Manager. For more information, see Section 25.5, "Integrating Flexfield Task Flows into Oracle Fusion Functional Setup Manager".
Descriptive flexfields let you satisfy different groups of users without having to reprogram your application, by enabling you to provide customizable fields for non-key attributes. Descriptive flexfields also enable context-sensitive fields that appear only when needed. In essence, a descriptive flexfield enables customers to extend the data model without writing either XML or Java. A 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 customers form would normally 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, since these are attributes of the customer entity 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 keep track of. You can add a descriptive flexfield to the 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 users enter on other parts of the page.
You could use a descriptive flexfield in a fixed assets application that you build to allow further description of a fixed asset. You could let the structure of the assets flexfield depend on the value of an asset type field. For example, a company could configure the flexfield 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."
Oracle General Ledger includes a descriptive flexfield in its journal entry form that implementers can configure to allow users to add information of their own choosing. For example, end users might need 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 customer implementers, consider defining a descriptive flexfield for every entity in your application to which a customer might need to add attributes.
Flexfields are modeled as a collection of Oracle Application Development Framework (ADF) polymorphic view rows. In a polymorphic collection, 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 should be used. Given a collection of polymorphic view rows, each row can be a different type.
The attribute sets associated with the discriminator are predefined. In fact, the Oracle Application Development Framework enables each view row to have its own view definition. When a polymorphic collection is created, the framework selects a view definition for the row to be added based on the value of the discriminator attribute.
With flexfields, this behavior is exposed using the terminology of segments and structures in place of attributes and view row types, respectively. The attributes in each view row definition are exposed as a set of segments with a predefined structure (or segment inclusion and ordering). The structure can include the discriminator attribute, common attributes that are unaffected by the discriminator value, and variable attributes that are included based on the discriminator value.
For descriptive flexfields, the context segment is the discriminator attribute, and the global segments are the common attributes.
Descriptive flexfields use a context switching mechanism similar to that of polymorphic view objects. You use a wizard to generate a flexfield polymorphic view object based on the descriptive flexfield definition, then create a view link to connect your product view object and the flexfield view object. You can then use the view object to add the flexfield to an application page.
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 be defaulted using a constant value from an underlying entity object, it is initialized to that value.
If a segment is defined to be defaulted by derivation using a descriptive flexfield parameter, 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 Oracle Fusion Middleware Fusion Developer's Guide for 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 Section 22.14, "Accessing Descriptive Flexfields from an ADF Desktop Integration Excel Workbook" and the Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework.Whenever you have an application table that you think customers might need to extend for their specific circumstances, you can add additional columns to the table and register those columns as flexfield segments. Once you have registered a flexfield, you have the ability to reuse the flexfield with other application tables.
To complete the process for developing a descriptive flexfield:
Add extension columns to the application table.
Register the flexfield and define its metadata and base table usage. You can register the flexfield using a registration task or using procedures from the FND_FLEX_DF_SETUP_APIS PL/SQL package.
Optionally reuse the flexfield by adding the same set of extension columns to other application tables.
Register all reuses using either a registration task or procedures from the FND_FLEX_DF_SETUP_APIS PL/SQL package.
Register the entity details for each usage.
Register flexfield parameters to identify external reference data sources for setting defaults and validating value sets. You can register the parameters using a registration task or using the procedures from the FND_FLEX_DF_SETUP_APIS PL/SQL package.
To implement a descriptive flexfield for an application 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 ATTRIBUTE1_VARCHAR2 and ATTRIBUTE12_NUMBER, that you think the customers will need. A segment column must be a VARCHAR2, NUMBER, DATE, or TIMESTAMP. When defining a flexfield attribute, the implementer will need to map the 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 ATTRIBUTEn_VARCHAR2, ATTRIBUTEn_NUMBER, ATTRIBUTEn_DATE, and ATTRIBUTEn_TIMESTAMP. 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 implementation-defined context codes.
Each implementer can configure as many of the segment columns as the customer requires and can choose whether to use the context column.
You must use the Database Schema Deployment Framework tools to create the application table and columns. Using these tools ensures that the table and its columns are registered in the Applications Core Data Dictionary. For more information, see Chapter 56, "Using the Database Schema Deployment Framework."
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.
Define the base table usage.
Define the base table column to be used for the context segment.
Map the base table columns to the flexfield segments.
You can define a descriptive flexfield using a registration task, which you access from the Oracle Fusion Applications Setup and Maintenance work area, or using the FND_FLEX_DF_SETUP_APIS PL/SQL package.
You can use the Register Descriptive Flexfields task, which is accessed from the Oracle Fusion Applications Setup and Maintenance work area, to register and define a descriptive flexfield. First you add a descriptive flexfield entry, then you define the base table usage. This becomes the master usage for the flexfield. You next specify which base table column to use for the context segment, and you define the base table columns to be used for the flexfield segments. You can then specify the name of the entity object, the package name, and the prefix to use when generating the flexfield's business components, or you can complete that task at a later time.
Tip:
You can also define and register a flexfield using the
FND_FLEX_DF_SETUP_APIS PL/SQL package, as described in Section 22.2.2.2, "Registering and Defining Descriptive Flexfields Using the Setup APIs.".Before you begin:
Create the extension columns as described in Section 22.2.1, "How to Create Descriptive Flexfield Columns."
To register and define a descriptive flexfield using a registration task:
In the Oracle Fusion Applications global area, choose Setup and Maintenance from the Administration menu.
Go to the Register Descriptive Flexfields task.
From the Search Results section, select Actions > New.
On the Create Descriptive Flexfield page shown in Figure 22-1, set the following values:
Descriptive Flexfield Code: Provide a code that uniquely identifies the flexfield.
Descriptive Flexfield Name: Provide a descriptive name for the flexfield.
Description: Provide a short description of the flexfield.
Application Name: Select the application name that has been assigned for the product area.
Module: Select the seed data module.
Delimiter: Select the character to be displayed between flexfield segments, when the segments are displayed in a concatenated format.
Click Save and Close.
In the Search Results section, select the flexfield that you just created and click Primary Table.
In the Descriptive Flexfield Table section of the Manage Flexfield Primary Table and Columns page, choose Actions > New.
On the Create Table Usage page shown in Figure 22-2, set the following values to define the base table usage for the flexfield:
Table Usage Code: Provide a code that uniquely identifies the flexfield usage. For the base table usage, this is typically the same code as the flexfield code.
Table Name: Type or select the name of the database table that contains the columns to be used as flexfield segments.
Description: Provide a short description of the flexfield usage.
Click Save and Close.
In the Table Name Column Details tab, choose Actions > New.
Select Context Segment from the Column Usage Type dropdown list.
From the Column Name 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.Repeat the following steps for each table column that you want to map to a flexfield segment, as shown in Figure 22-3.
In the Column Details tab, choose Actions > New.
Select Segment from the Column Usage Type dropdown list.
Select the database column from the Column Name dropdown list that you want to map to a segment of the flexfield.
Click Save and Close.
You can register the entity details now or later. However, this step must be completed before you can generate the flexfield usage's business components. For more information, see Section 22.2.5, "How to Register Entity Details."
(Optionally) Register secondary usages of the flexfield as described in Section 22.2.4, "How to Register the Reuse of a Descriptive Flexfield."
In addition to using a registration task, as described in Section 22.2.2.1, "Registering and Defining Descriptive Flexfields Using a Registration Task," you can define and register a descriptive flexfield using procedures from the FND_FLEX_DF_SETUP_APIS PL/SQL package. This package also has procedures for updating, deleting, and querying about flexfield definitions.
To learn how to access documentation about using the FND_FLEX_DF_SETUP_APIS PL/SQL package, see Section 22.2.2.2.1, "What You May Need to Know about the Descriptive Flexfield Setup API."
Before you begin:
Create the extension columns as described in Section 22.2.1, "How to Create Descriptive Flexfield Columns".
To register and define a descriptive flexfield using the setup APIs:
Run the fnd_flex_df_setup_apis.create_flexfield(...) procedure to register the descriptive flexfield, its context segment, and its master usage.
Run the fnd_flex_df_setup_apis.create_segment_column_usage(...) procedure for each segment column to register the segment columns.
(Optionally) Register the entity details as described in Section 22.2.5, "How to Register Entity Details." This step must be completed before you can generate the flexfield usage's business components.
In the descriptive flexfield development process, you 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 outputs package documentation and usage examples to 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
A descriptive flexfield configuration can be shared with other application tables. To reuse a descriptive flexfield, you add the same set of extension columns to the application table for which you want to reuse the flexfield, and you register the reuse as described in Section 22.2.4, "How to Register the Reuse of a Descriptive Flexfield."
The application table that was used to first register the flexfield is referred to as the master application table, and it is the owner of the flexfield. 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 master table. The secondary extension columns must have the same data type and size as the corresponding master table extension columns.
The column names must also be exactly the same as in the master usage, with the exception of an optional prefix. For example, if the column names are ATTRIBUTE1 and ATTRIBUTE2 in the master usage, 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 and HOME_ATTR2, or any variation that does not end in the names of the master usage columns.
You must use the Database Schema Deployment Framework tools when you create the application table and columns. Using these tools ensures that the table is registered in FND_TABLES, and its columns are registered in FND_COLUMNS.
After you add extension columns to a table for a reuse of a flexfield, you must register the usage before you can build a descriptive business component for the secondary usage.
You can register the reuse of a descriptive flexfield using a registration task or using procedures from the FND_FLEX_DF_SETUP_APIS PL/SQL package.
You can use the Register Descriptive Flexfields task, which is accessed from the Oracle Fusion Applications Setup and Maintenance work area, to register the reuse of a descriptive flexfield by a secondary table. The registration task uses the master usage column mappings to determine how to map the secondary table's column names to the flexfield segments. If you specify a prefix, the task uses the prefix to determine the column mappings. For example, if the master table's ATTRIBUTE1 column is mapped to a segment, and you specify a prefix of HOME for the secondary usage, the task automatically maps its HOME_ATTRIBUTE1 column to a flexfield segment.
Tip:
You can also register the reuse of a flexfield using the
FND_FLEX_DF_SETUP_APIS PL/SQL package, as described in Section 22.2.4.2, "Registering the Reuse of a Descriptive Flexfield Using the Setup APIs.".Before you begin:
Register the descriptive flexfield and its master usage as described in Section 22.2.2, "How to Register and Define Descriptive Flexfields."
Create the extension columns for the reuse as described in Section 22.2.3, "How to Reuse a Descriptive Flexfield on Another Table."
To register a secondary reuse using a registration task:
In the Oracle Fusion Applications global area, choose Setup and Maintenance from the Administration menu.
Go to the Register Descriptive Flexfields task.
In the Search Results section select the flexfield for which you want to add a secondary usage and click Secondary Tables.
In the Descriptive Flexfield Table section of the Manage Flexfield Secondary Tables and Columns page, choose Actions > New.
On the Create Table Usage page, set the following values to define the secondary table usage for the flexfield:
Table Usage Code: Provide a code that uniquely identifies the flexfield usage.
Table Name: Select the name of the database table that contains the columns to be used as flexfield segments for this secondary usage.
Column Name Prefix: If you used a prefix for the flexfield column names, type the prefix.
Description: Provide a short description of the flexfield usage.
Click Save and Close.
You can register the entity details now or later. However, this step must be completed before you can generate the flexfield usage's business components. For more information, see Section 22.2.5, "How to Register Entity Details."
In addition to using the registration task, as described in Section 22.2.4.1, "Registering the Reuse of a Descriptive Flexfield Using a Registration Task," you can define and register the reuse of a descriptive flexfield using procedures from the FND_FLEX_DF_SETUP_APIS PL/SQL package.
To learn how to access documentation about using the FND_FLEX_DF_SETUP_APIS PL/SQL package, see Section 22.2.2.2.1, "What You May Need to Know about the Descriptive Flexfield Setup API."
The definition of a descriptive flexfield usage includes the following information:
The table name
The code for identifying the secondary usage
The column name prefix. For example, if the master table column is ATTRIBUTE1, and the secondary table column is HOME_ATTRIBUTE1, then the prefix is HOME_.
Before you begin:
Register the descriptive flexfield and its master usage as described in Section 22.2.2, "How to Register and Define Descriptive Flexfields."
Create the extension columns for the reuse as described in Section 22.2.3, "How to Reuse a Descriptive Flexfield on Another Table."
To register a secondary reuse using the setup APIs:
To register the secondary reuse of a descriptive flexfield, run the fnd_flex_df_setup_apis.create_flex_table_usage(...)procedure.
(Optionally) Register the entity details as described in Section 22.2.5, "How to Register Entity Details." This step must be completed before you can generate the flexfield usage's business components.
When you build the flexfield business components and create flexfield-specific application module instances, the flexfield modeler requires the following information about the flexfield usage:
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 can have its own package name.
You can use a registration task or the FND_FLEX_DF_SETUP_APIS PL/SQL package to register this information for a flexfield usage.
You can use the Register Descriptive Flexfields task, which is accessed from the Oracle Fusion Applications Setup and Maintenance work area, to register a flexfield usage's entity details.
Tip:
You can also register entity details using theFND_FLEX_DF_SETUP_APIS PL/SQL package, as described in Section 22.2.4.2, "Registering the Reuse of a Descriptive Flexfield Using the Setup APIs."Before you begin:
Register the usage as described in Section 22.2.2, "How to Register and Define Descriptive Flexfields" and Section 22.2.4, "How to Register the Reuse of a Descriptive Flexfield."
Ensure that the entity object for the usage's table exists.
To register the entity details using a registration task:
In the Oracle Fusion Applications global area, choose Setup and Maintenance from the Administration menu.
Go to the Register Descriptive Flexfields task.
In the Search Results section select the flexfield for which you want to add entity details and click Primary Table for the master usage or click Secondary Tables for a secondary usage.
Select the usage and click the Table Name Entity Details tab, as shown in Figure 22-4.
If no row exists in the Entity Details section, choose Actions > New to create a row.
Set the following values:
Entity Object: Provide the full class name of the table's entity object.
Object Name Prefix: Type 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.
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.hcm.payroll.flex.dff1, then you cannot define the oracle.apps.hcm.payroll.flex package for another usage, because that package would then identify both usages. Instead, you could use oracle.apps.hcm.payroll.flex.dff2.Click Save and Close.
In addition to using the registration task, as described in Section 22.2.5.1, "Registering Entity Details Using a Registration Task," you can register entity details using procedures from the FND_FLEX_DF_SETUP_APIS PL/SQL package.
To learn how to access documentation about using the FND_FLEX_DF_SETUP_APIS PL/SQL package, see Section 22.2.2.2.1, "What You May Need to Know about the Descriptive Flexfield Setup API."
Before you begin:
Register the usage as described in Section 22.2.2, "How to Register and Define Descriptive Flexfields" and Section 22.2.4, "How to Register the Reuse of a Descriptive Flexfield."
Ensure that the entity object for the usage's table exists.
To register the entity details using the setup APIs:
Run the fnd_flex_df_setup_apis.create_adfbc_usage(...)procedure to register the entity object, package name, and object name prefix for the flexfield usage.
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. Implementers 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 following ways:
At row creation time to provide default segment values.
In derived segments, whose values automatically change to reflect new reference values.
In the WHERE clauses for table validated 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, application implementers are guaranteed that the parameters will always be mapped to entity object attributes, and they can use the parameters at will.
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 (non-flexfield) 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 implementer 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 Section 22.3, "Creating Descriptive Flexfield Business Components" and Section 22.8.3, "How to Configure Descriptive Flexfield Parameters".
You can use the Register Descriptive Flexfields task, which is accessed from the Oracle Fusion Applications Setup and Maintenance work area, to register a flexfield parameter.
Tip:
You can also register parameters using theFND_FLEX_DF_SETUP_APIS PL/SQL package, as described in Section 22.2.6.1, "Registering a Flexfield Parameter Using a Registration Task."To register a parameter using a registration task:
In the Oracle Fusion Applications global area, choose Setup and Maintenance from the Administration menu.
Go to the Register Descriptive Flexfields task.
In the Search Results section select the flexfield for which you want to add a parameter and click Parameters.
In the Parameters section of the Manage Flexfield Parameters page, choose Actions > New.
In the Parameters section shown in Figure 22-5, set the following values to define a parameter for the flexfield:
Parameter Code: Provide a code that uniquely identifies the parameter for the given flexfield.
Description: Provide a brief description of the parameter.
Enabled: Select this checkbox.
Click Save and Close.
In addition to using the registration task, as described in Section 22.2.6.1, "Registering a Flexfield Parameter Using a Registration Task," you can register a flexfield parameter using procedures from the FND_FLEX_DF_SETUP_APIS PL/SQL package.
To learn how to access documentation about using the FND_FLEX_DF_SETUP_APIS PL/SQL package, see Section 22.2.2.2.1, "What You May Need to Know about the Descriptive Flexfield Setup API."
Before you begin:
Define and register the flexfield as described in Section 22.2.2, "How to Register and Define Descriptive Flexfields."
To create a parameter using the setup APIs:
Run the fnd_flex_df_setup_apis.create_parameter(...) procedure and provide a parameter code and data type.
Before you can use a descriptive flexfield in an application, you must generate flexfield Business Components for the flexfield. You generate these components by running a flexfield Business Component modeler. The modeler 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 application view object, and the context attribute, which serves as the discriminator.
When implementers configure the flexfields by defining global and context-sensitive segments, the base view object is regenerated and additional flexfield view objects are generated. Figure 22-6 shows an example of the configured components. The application view object contains only the non-flexfield 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 view object definition that represents the structure of the rows with that context value.
Note:
The application view object might contain other attributes. However, the application view object must not include flexfield view object attributes.None of the flexfield view objects contains the fixed (non-flexfield) columns.
No Java implementation classes are generated for descriptive flexfield view objects. The application view object may or may not have Java implementation classes.
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.
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 Oracle Fusion Applications Extensibility Guide.
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, it must have a programmatically defaulted primary key.
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 Section 22.2.5, "How to Register Entity Details."
To create descriptive flexfield business components:
Build your project to ensure that the entity objects are available in classes. The modeler relies on what is in your classes.
From the File menu, choose New.
In the New Gallery, navigate to Business Tier > ADF Business Components and select Flexfield Business Components.
Click OK.
On the Role page of the Create Flexfield Business Components wizard, select the role that you are taking as you create the flexfield business components:
Developer — select this role if you are incorporating the flexfield into an application. The business components must be stored in one of your projects. Select the desired project location from the Project Source Path dropdown list.
Tester — select this role if you are planning to test your flexfield or a shared flexfield. In the Output Directory field, specify the path of your desired location for the generated business components.
For more information about testing flexfields and importing shared flexfields, see Chapter 25, "Testing and Deploying Flexfields."
Note:
This is not a role in the security sense. It exists only during this procedure, for the purpose of specifying where your generated flexfield business components should be stored.Click Next. The Flexfield page appears, as shown in Figure 22-7.
From the Type dropdown list, select Descriptive.
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.
In the Code field, specify the code of the descriptive flexfield you want to use.
You can browse for and filter by Code.
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 master usage of the descriptive flexfield on the application table where it was originally defined. Every descriptive flexfield has one master usage.
A reuse (secondary usage) of the descriptive flexfield on an application table, including the one on which it was originally defined. Zero or more reuse instances can be defined for a given flexfield, each one potentially on a different application table. You can identify reuse instances by the presence of the prefix (Reuse) in the Description field.
Click Next.
On the Entity Object page, expand the tree of available models and select an entity object to use as the data source for the descriptive flexfield, as shown in Figure 22-8.
The entity object you select must include all of the attributes representing the columns that are reserved for the descriptive flexfield.
Descriptive flexfield attributes will be validated by the entity object along with its other attributes.
You might wish to select an entity object for which the descriptive flexfield attributes are defined as transient (not based on database table columns). If you need to do this, select the checkbox labeled Use the entity attributes named after their corresponding flexfield database columns. This checkbox is unselected by default.
When a descriptive flexfield entity object attribute is transient, there is no matching underlying column name. When you select this checkbox, 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. Make sure 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 base table 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 Section 22.2.5, "How to Register Entity Details."
Note:
If the entity object with transient descriptive flexfield attributes is not based on the base table 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 Section 22.2.3, "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 upper case.Click Next.
The Naming page displays the entity object's package name and object name that you registered for the usage, as described in Section 22.2.5, "How to Register Entity Details." Review the names and click Next.
If the selected entity object is not registered with the flexfield usage, the Naming page displays a message to that effect. Take one of the following actions:
Click Back to return to the Entity Object page and select an entity object that has been properly registered.
Click Cancel to exit this wizard and register the entity object that you want to use.
For information about registering the entity object with the flexfield usage, see Section 22.2.5, "How to Register Entity Details."
On the Parameters page shown in Figure 22-9, 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.
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 on 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 which is directly associated with the flexfield entity object through an accessor.
Attributes that are part of any entity object which 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.When all of the defined parameters are mapped, click Next.
On the Summary page, review your choices and 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 application project. You can resolve this issue by manually adding any missing libraries; then you can complete this procedure successfully.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.
A view link is needed whenever an application view object references your descriptive flexfield. The application view object and the flexfield base view object are linked through their primary keys.
You create a view link to connect your product view object with the flexfield view object. Once you have created the view link, you can use the view object to add the flexfield to an application page.
Before you begin:
Create the master view object, which contains only non-flexfield attributes.
Create the flexfield business components for the descriptive flexfield as described in Section 22.3.1, "How to Create Descriptive Flexfield Business Components".
To create a descriptive flexfield view link:
From the File menu, choose New.
In the New Gallery, navigate to Business Tier > ADF Business Components and select Flexfield View Link.
Click OK to access the Create Flexfield View Link wizard, as shown in Figure 22-10.
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 recreate it with the new package name.In the Name field, enter a name for the view link.
Click Next. The View Objects page appears, as shown in Figure 22-11.
In the Select Source View Object tree, expand the available objects from your current project and select the master view object.
In the Select Destination Flexfield tree, expand the application and select a destination flexfield usage.
In the View Link Accessor Name field, enter an appropriate name for the view link accessor.
Click Next.
Review the information on the Source Attributes page and 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.On the Summary page, review the summary, then click Finish.
You must nest the descriptive flexfield application module instance under the project application module before you can incorporate the descriptive flexfield usage into the UI.
You only need to nest one flexfield application module for a flexfield usage, even if two or more view links exist for the same flexfield usage.
You use the overview editor for your application module to nest the descriptive flexfield application module instance. The nested descriptive flexfield application module instance shares the same transaction and entity object caches as the application module.
Before you begin:
You should have already created the project application module. For information about creating application modules, see the "Implementing Business Services with Application Modules" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
Create the master view object, which contains only non-flexfield attributes.
Create a flexfield business component for the descriptive flexfield usage as described in Section 22.3.1, "How to Create Descriptive Flexfield Business Components."
To nest the descriptive flexfield application module instance in the application module:
In the Application Navigator, double-click the project application module.
Click the Data Model navigation tab.
On the Data Model Components page, expand the Application Module Instances section, as shown in Figure 22-12.
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 Section 22.2.5, "How to Register Entity Details."
Select the application module for the descriptive flexfield and shuttle 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 Section 22.2.5, "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.
You need to add a flexfield view object instance that reflects the hierarchy of the view link that you created in Section 22.4.1, "How to Create Descriptive Flexfield View Links" to the application module for your application.
You edit the project application module to add the flexfield view object.
Before you begin:
You should have already created the project application module. For information about creating application modules, see the "Implementing Business Services with Application Modules" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
Create the master view object, which contains only non-flexfield attributes.
Create the flexfield business components for the descriptive flexfield usage as described in Section 22.3.1, "How to Create Descriptive Flexfield Business Components".
Create the flexfield view link as described in Section 22.4.1, "How to Create Descriptive Flexfield View Links."
To add a descriptive flexfield view object to the application module:
In the Application Navigator, double-click the project application module.
Click the Data Model navigation tab
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 22-13.
To include a descriptive flexfield on an application page, you add the flexfield UI component to the page, and then configure the properties of the UI component.
Note:
You can also use descriptive flexfields in the following ways:Incorporate descriptive flexfield view object attributes as search criteria in an advanced query search form.
See Section 22.11, "Incorporating Descriptive Flexfields Into a Search Form".
Use ADF Desktop Integration to incorporate descriptive flexfields into an Excel workbook.
See Section 22.14, "Accessing Descriptive Flexfields from an ADF Desktop Integration Excel Workbook".
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 component is wrapped 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 method of adding flexfields to your application. The UI-first method is also available, but is not documented here.Use this procedure to incorporate your descriptive flexfield into a basic form.
Before you begin:
Create the descriptive flexfield view object as described in Section 22.3.1, "How to Create Descriptive Flexfield Business Components".
Create the view link as described in Section 22.4.1, "How to Create Descriptive Flexfield View Links".
Nest the descriptive flexfield application module instance in the project application module as described in Section 22.5.1, "How to Nest the Descriptive Flexfield Application Module Instance in the Application Module".
Add the view object instance to the application module as described in Section 22.6.1, "How to Add a Descriptive Flexfield View Object Instance to the Application Module".
To add a descriptive flexfield UI component to a form:
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.
When prompted, select ADF Form or select Applications > Panel.
In the Data Controls panel, expand the master view object and find the flexfield view object, as shown in Figure 22-14.
Caution:
You must use the flexfield view object child of the master view object. Do not use the flexfield view object from the flexfield's application module data control.Drag the flexfield view object onto a form, and select the appropriate flexfield UI component.
Tip:
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.Tip:
If a descriptive flexfield is in a region, such as a header, subheader, or tab, that does not contain core fields, there is a possibility that the customer will not use the flexfield segments and the region will be empty. To avoid the display of an empty region on the page, you should add controlling logic to hide the region if the customer has not defined the segments that appear in the region. For information about how to determine if a segment has been defined, see Section 22.10.2, "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 Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development FrameworkTip:
You can place the segments in a multiple-column layout, such as a two or three column layout. You should use a multiple-column layout when the number of segments that will be added by the customer 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 user will have to scroll to see any fields that appear below the flexfield.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 panelFormLayout component, with each row's content based on a different context value. For more information, see the "Arranging Content in Forms" section of the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.Use this procedure to allow for the full range of possible context segment values. Users will be able to expose or hide the context-sensitive segments of the flexfield separately for each row of data.
Before you begin:
Create the descriptive flexfield view object as described in Section 22.3.1, "How to Create Descriptive Flexfield Business Components".
Create the view link as described in Section 22.4.1, "How to Create Descriptive Flexfield View Links".
Nest the descriptive flexfield application module in the project application module as described in Section 22.5.1, "How to Nest the Descriptive Flexfield Application Module Instance in the Application Module".
Add the view object instance to the application module as described in Section 22.6.1, "How to Add a Descriptive Flexfield View Object Instance to the Application Module".
To add an unrestricted descriptive flexfield UI component to a table:
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.
When prompted, select ADF Table or Applications > Table. Be sure to select the Row Selection option, and set the appropriate width.
In the Data Controls panel, expand the master view object and find the flexfield view object.
Caution:
You must use the flexfield view object child of the master view object. Do not use the flexfield view object from the flexfield's application module data control.Drag the flexfield view object onto the table on the design tab, as shown in Figure 22-15, and select Oracle Descriptive Flexfield Column as the UI component. This creates the base flexfield column in the table will the global segments will render.
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.Create a detail region (detailStamp facet) if the table does not have one, as shown in Figure 22-16.
Add a panel layout control to the detailStamp facet if you do not already have one.
Drag and drop the same flexfield view object into the detail facet on the Source tab or the structure view as shown in Figure 22-17; this creates the context sensitive fields.
Normally, 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 appear 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:
Create the descriptive flexfield view object as described in Section 22.3.1, "How to Create Descriptive Flexfield Business Components".
Create the view link as described in Section 22.4.1, "How to Create Descriptive Flexfield View Links".
Nest the descriptive flexfield application module in the project application module as described in Section 22.5.1, "How to Nest the Descriptive Flexfield Application Module Instance in the Application Module".
Add the view object instance to the application module as described in Section 22.6.1, "How to Add a Descriptive Flexfield View Object Instance to the Application Module".
To add a descriptive flexfield UI component to a table as columns:
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.
When prompted, select ADF Table or Applications > Table. Be sure to select the Row Selection option, and set the appropriate width.
In the Data Controls panel, expand the master view object and find the flexfield view object.
Caution:
You must use the flexfield view object child of the master view object. Do not use the flexfield view object from the flexfield's application module data control.Drag the flexfield view object onto the table on the design tab as shown in Figure 22-15, 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.Edit the JSP source code for this page, and remove the following attribute from the <fnd:descriptiveFlexfield> tag:
mode="global"
See Table 22-1 for information about the mode attribute.
Add an additional 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 value segment will be visible on the page, be sure to configure the segment to be read-only so end users cannot modify it. For more information, see Section 22.8.2, "How to Configure Segment-Level UI Properties".
If your ADF Table component is wrapped in an Applications Table component, and if you are using your own CreateInsert 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
From the Data Controls panel, drag the appropriate operation of the master view object (such as CreateInsert) onto the page.
Delete the newly created button, but not its pageDef entry. Example 22-1 shows an example of the pageDef entry.
Example 22-1 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>
Add a new button to the layout.
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 22-1 shows how the executables element of the page definition might look. Dff1RefInstanceIterator is the iterator of the master view object.
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 22-2.
Example 22-2 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);
}
Add code to the custom createInsert method to handle an empty table as described in Section 22.7.5, "How to Add a Row to an Empty Table in a Custom createInsert Method"
Caution:
Please keep the following caveats in mind: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 Section 22.8.1, "How to Configure Flexfield-Level UI Properties" and Section 22.8.2, "How to Configure Segment-Level UI Properties".
If you are using a custom createInsert method to add rows to an ApplicationTable component, you must include code similar to Example 22-3 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 22-3 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();
}
}
}
}
}
If your flexfield is in an ADF Table component 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 handler 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 22-4 shows an example of a custom flexfield handler for a query event. The method first calls invokeMethodExpression to call the original query listener, and then calls updateFlexColumns with the table component that contains the flexfield as the parameter. Example 22-5 shows the binding of the custom flexfield handler to the query component.
Example 22-4 Flexfield Listener
public void customDffSearchQueryListener(QueryEvent queryEvent)
{
invokeMethodExpression(
"#{bindings.DffCriteriaQuery.processQuery}",
Object.class,QueryEvent.class,queryEvent);
DescriptiveFlexfield.updateFlexColumns(appTable);
}
Example 22-5 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"/>
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.Descriptive flexfield segments appear on a form as a widget with a customer-defined label, just as core fields do. In tabular layout, the label of the flexfield segment is the column header and the values are within each cell of the column.
Figure 22-18 shows an example of a descriptive flexfield used in a form on an application page.
Figure 22-19 shows an example of a descriptive flexfield used in a table on an application page:
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.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.
You configure flexfield-level behavior by configuring the UI component's properties.
Before you begin:
Add the descriptive flexfield to the page as described in Section 22.7, "Adding Descriptive Flexfield UI Components to a Page".
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 22-20.
The significant properties on the Common, Data, Style and Behavior property tabs are listed in Table 22-1:
Table 22-1 Descriptive Flexfield Properties
| Tab > Property | Description |
|---|---|
|
Common > Id |
The ID of the flexfield. |
|
Common > Rendered |
Indicates whether the flexfield is rendered on the page. Values can be |
|
Common > Value |
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 |
The name of the accessor between the product team view object and the flexfield view object. |
|
Data > Category |
Defines which category will be rendered on the page. The category can be set on each attribute's custom property. |
|
Style > StyleClass |
The style class of the flexfield. |
|
Style > InlineStyle |
The inline style of the component. |
|
Behavior > Read-Only |
Indicates whether the flexfield is rendered as read-only. Values can be |
|
Behavior > Mode |
Defines the UI mode of the descriptive flexfield component, to render all of the segments or just some of them. Values can be:
|
|
Behavior > partialTriggers |
The IDs of the components that should trigger a partial update in the flexfield ( |
|
Behavior > valueChangeListener |
A method reference to a value change listener ( |
|
Behavior > binding |
An EL reference that will store the component instance on a bean ( |
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.
Descriptive flexfields support finer control of segments in the UI through the following segment-level boolean properties:
rendered — Indicates whether the segment is visible on the application page.
required — Indicates whether the segment must have a value.
readOnly — Indicates whether users can modify the segment.
The default values of these properties are derived from the flexfield metadata, but you can override them by inserting customization elements into the UI metadata. You can set these properties in the flexfield XML with literal values or EL expressions in most cases.
Note:
If you set a segment's
required property to True in the flexfield metadata, for validation purposes you cannot override this by resetting it to False in the page metadata. You can, however, do the reverse: change a non-required segment to required in the page metadata.For information about using EL expressions, see the "Creating ADF Data Binding EL Expressions" section in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
Before you begin:
Add the descriptive flexfield to the page as described in Section 22.7, "Adding Descriptive Flexfield UI Components to a Page".
To configure segment-level UI properties:
In the Applications page of the Component Palette, drag the following components onto the descriptive flexfield component:
Use to configure the descriptive flexfield context segment. This component must be inserted as a child of the Descriptive Flexfield component.
You can configure any combination of the ReadOnly, Rendered, and Required properties.
Use to configure global segments, or as a wrapper for the Flexfield Segment Hint component to configure individual segments. This component must be inserted as a child of the Descriptive Flexfield component. Apply the properties as follows:
To configure all global segments, do not provide a value for the ContextCode property. Configure any combination of the ReadOnly, Rendered, and Required properties.
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.To configure specific global segments, omit all properties and insert one or more Flexfield Segment Hint components as children.
To configure all context-sensitive segments within a particular context, provide a value for the ContextCode property and configure any combination of the ReadOnly, Rendered, and Required properties.
To configure specific context-sensitive segments within a particular context, provide a value for the ContextCode property and insert one or more Flexfield Segment Hint components as children.
Note:
This property does not affect the descriptive flexfield context segment. For context segment configuration, see the entry for Flexfield Context Segment Hints.Use to configure individual global or context-sensitive segments. This element must be inserted as a child of the Flexfield Segment Hints component.
Specify the SegmentCode, which should identify a context-sensitive segment within a particular context if the parent element contains a ContextCode value, or a global segment if not.
You can configure any combination of the Rendered, Required, or ReadOnly properties. The ReadOnly property is generally set when there is a default value assigned to that segment, and you do not want users to choose a value other than the default. You only should set both Required and ReadOnly to true if the segment has a default value
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.To determine the correct value for the SegmentCode property, examine the FND_ACFF_SegmentName attribute of the context-sensitive segment's viewAttribute element in your descriptive flexfield view object.
Example 22-6 shows various combinations of the segment-level display properties in the flexfield XML
Example 22-6 Segment-Level Display Properties in Descriptive Flexfield Metadata
<fnd:descriptiveFlexfield value="#{bindings.Dff1Iterator}">
<!-- Customize the context segment. -->
<fnd:flexfieldContextSegmentHint rendered="#{expr}"/>
<!-- Customize all global segments.
For a descriptive flexfield that was added as table columns,
the rendered property must apply to the entire column.
-->
<fnd:flexfieldSegmentHints rendered="#{expr}"
required="#{expr}"
readOnly="#{expr}"/>
<!-- Customize a specific global segment.
For a descriptive flexfield that was added as table columns,
the rendered property must apply to the entire column.
-->
<fnd:flexfieldSegmentHints>
<fnd:flexfieldSegmentHint segmentCode="GlobalX"
rendered="#{expr}"
required="#{expr}"
readOnly="#{expr}"/>
</fnd:flexfieldSegmentHints>
<!-- Customize all segments for a certain context.
This does not affect the context segment. The hint for the context
segment is specified by flexfieldContextSegmentHint.
-->
<fnd:flexfieldSegmentHints contextCode="Context5" readOnly="#{expr}"/>
<!-- Customize a specific context-sensitive segment. -->
<fnd:flexfieldSegmentHints contextCode="Context3">
<fnd:flexfieldSegmentHint segmentCode="Extra 1"
rendered="#{expr}"
required="#{expr}"
readOnly="#{expr}"/>
</fnd:flexfieldSegmentHints>
<fnd:descriptiveFlexfield/>
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:
Define and register the necessary parameters, if any, as described in Section 22.2.6, "How to Register Descriptive Flexfield Parameters".
Add the descriptive flexfield to the page as described in Section 22.7, "Adding Descriptive Flexfield UI Components to a Page".
To configure descriptive flexfield parameters:
Identify each UI component that corresponds (through the flexfield view object) to an entity object attribute to which a flexfield parameter is mapped, and make sure 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.
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 22-7 shows the source view of the partialTriggers attribute.
Any implementation of flexfields in Oracle Fusion Applications typically requires application seed data, which is the essential data to enable flexfields to work properly in applications. Flexfield seed data can be uploaded and extracted using Seed Data Loader.
After you complete the registration process described in Section 22.2.2, "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 implementer. In addition to the registration data, your flexfield seed data might include contexts, segments, and value sets that you have defined for your flexfield.
For information about extracting and loading seed data, see Chapter 55, "Initializing Oracle Fusion Application Data Using the Seed Data Loader".
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
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 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.
Your application might find it useful to know if any global or context-sensitive segments exist in a descriptive flexfield's metadata before deciding whether to invoke 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.
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 ValueChangeEvent, and the listener is called.
Before you begin:
Add the descriptive flexfield to the page as described in Section 22.7, "Adding Descriptive Flexfield UI Components to a Page".
To Configure a Descriptive Flexfield to Handle Value Change Events
Create the listener handler as a Java method (usually on a backing bean). Example 22-8 is an example of a method that handles a ValueChangeEvent.
Example 22-8 Sample Listener Handler
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());
}
Specify the handler method as UI metadata on the flexfield's valueChangeListener property (described in Table 22-1). In the Property Inspector, click the Edit button for valueChangeListener, and a wizard appears to help you select an existing event listener or create a new listener. Example 22-9 is an example of the metadata as an EL expression that identifies the dffChangeListener listener from the Java method in Example 22-8.
For more information about handling value change events, see the "Using Input Components and Defining Forms" chapter in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework.
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.
You 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 a Query Panel with results to incorporate a descriptive flexfield into a search form.
To add a descriptive flexfield to a search form:
Add view criteria to the application view object instance that uses attributes from the view-linked descriptive flexfield view object, as shown in Figure 22-21.
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.
Select the discriminator and use it as the attribute in the view criteria definition.
Create a new JSPX page in the user interface project.
Tip:
JDeveloper names the user interface project
ViewController by default.In the Data Control panel, select the named view criteria that you created previously.
Drag and drop the view criteria onto the page as a Query Panel with results, as shown in Figure 22-22.
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 22-23.
For more information about working with search forms, see the "Creating ADF Databound Search Forms" chapter of Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
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.
While descriptive flexfields are modeled using polymorphic view objects, flexfield technology is not compatible with Oracle Business Intelligence, which also requires reference data, such as lookups, to be modeled as view-linked child view objects. To enable a descriptive flexfield to be used by Oracle Business Intelligence, it must be flattened into a usable static form.
When the business intelligence-enabled and flattened descriptive flexfield is configured as part of an application, the implementer or administrator can select which individual flexfield segments to make available for use with Oracle Business Intelligence.
To enable a descriptive flexfield to be flattened into a static form, you must designate the flexfield as business intelligence-enabled. You can set the business intelligence-enabled flag at registration time using the fnd_flex_df_setup_apis.create_flexfield(...) procedure, or you can set the flag later using the fnd_flex_df_setup_apis.update_flexfield(...) procedure. When you create business components for a descriptive flexfield, the business component modeler recognizes the business intelligence-enabled setting, and 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.
Note:
When you make changes to a business intelligence-enabled flexfield, you use the Import Metadata Wizard to import the changes into the Oracle Business Intelligence repository as described in the "Using Incremental Import to Propagate Flex Object Changes" section in the Oracle Fusion Middleware Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition (Oracle Fusion Applications Edition).Before you begin:
If you have not done so already, add the flexfield's extension columns to the application table as described in Section 22.2.1, "How to Create Descriptive Flexfield Columns".
Register the flexfield and define its metadata as described in Section 22.2.2, "How to Register and Define Descriptive Flexfields."
In order to expose the flexfield to Oracle Business Intelligence, the flexfield must be Business Intelligence (BI) enabled. If the flexfield was not Business Intelligence enabled when it was registered, you can use the fnd_flex_df_setup_apis.update_flexfield(...) procedure to change the flag.
If you want to expose segments to Oracle Business Intelligence, you can enable the segments for business intelligence using the Manage Descriptive Flexfields task, which is accessed from the Oracle Fusion Applications Setup and Maintenance work area.
To produce a business intelligence-enabled flattened descriptive flexfield model:
Create descriptive flexfield business components as described in Section 22.3, "Creating Descriptive Flexfield Business Components".
For a flexfield that is Business Intelligence enabled, the Create Flexfield Business Components wizard automatically generates the normal descriptive flexfield view object, as well as a business intelligence-specific view object and other business components under a directory called analytics in the package root directory.
Caution:
If your flexfield uses hierarchical value sets, you must make sure that the flattened tree view objects are already in your project; otherwise the wizard will report the missing view objects as errors.Create a view link using the procedure described in Section 22.4, "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 22-24.
Create an application module for use with Oracle Business Intelligence as described in Section 22.6, "Adding a Descriptive Flexfield View Object to the Application Module". Make the following changes:
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.
On the Application Modules page of the wizard, add an instance of the descriptive flexfield Oracle BI application module as a nested instance of this application module. You can identify the Oracle BI application module by the analytics subpackage under the package root.
Following Oracle BI EE development guidelines, define the custom properties required to link the master view object instance to the default view instance.
This is done on the General tab of the nested business intelligence-enabled flexfield application module instance definition, as shown in Figure 22-25.
As you do this, keep the following points in mind:
The default view instance inside the business intelligence-enabled flexfield application module is normally called DefaultFlexViewUsage.
The custom property names should be formatted as BI_VIEW_LINK_mypropertyname
The custom property values should 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 you specify in different application modules are created during import from Oracle ADF.
You can make access to a descriptive flexfield available through web services, which will enable you to perform CRUD (create, retrieve, update and delete) operations on the flexfield data rows. You accomplish this by exposing the descriptive flexfield application module as a web service and adding flexfield service data object support utility methods to the product application module.
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 22-6, 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 22-26 shows an application module tester view of a descriptive flexfield.
To complete the development process to publish descriptive flexfields as web services:
Expose the descriptive flexfield as a web service.
Test the web service.
You make web service access to descriptive flexfields available by adding a custom property to the view link, service-enabling the master view object, exposing the application module as a web service, exposing operations on the master view object, and adding utility methods for the flexfield to the product application module. You can then deploy the service and run Java client programs to test the service as described in Section 22.13.2, "How to Test the Web Service."
For more information about service enabling an application module, see "Integrating Service-Enabled Application Modules" in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework
Before you begin:
Create a flexfield business component for the flexfield's usage as described in Section 22.3.1, "How to Create Descriptive Flexfield Business Components."
Note:
When you generate a flexfield business component, the IDE automatically service enables the business component by generating a Service Data Object (SDO) for the base view object and for every subtype view object.Create a flexfield view link between the master view object, which contains only non-flexfield attributes, and the flexfield business component for the flexfield usage as described in Section 22.4.1, "How to Create Descriptive Flexfield View Links."
Nest the descriptive flexfield application module instance in the project application module as described in Section 22.5.1, "How to Nest the Descriptive Flexfield Application Module Instance in the Application Module."
Add the view object instance to the application module as described in Section 22.6.1, "How to Add a Descriptive Flexfield View Object Instance to the Application Module."
To expose a descriptive flexfield as a web service:
In the Application Navigator, open the view link between the master view object and the base flexfield view object.
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.
Open the master view object, which is the view object that contains only the non-flexfield attributes.
In the overview editor click the Java navigation tab.
In the Java Classes section, click the Edit icon to generate and configure Java implementation classes.
In the Select Java Options dialog, select Generate Service Data Object Class and click OK, as shown in Figure 22-27.
From the Application Navigator, open the product application module.
In the overview editor, click the Service Interface navigation tab.
If the Add icon is enabled, complete the following steps to service enable the application module and expose the master view object operations:
Click the Add icon to enable the application to support the Service interface.
In the Create Service Interface wizard, click Next twice to go to the Service View Instances page.
Shuttle the view instance for the master view object to the Selected list.
Select the master view object from the Selected list as shown in Figure 22-28, select all the operations in the Basic Operations list, and click OK.
Click Finish.
If the Add icon is disabled, the application is already service enabled. Complete the following steps to expose the master view object operations:
In the Service Interface View Instances section, click the Edit icon.
Shuttle the view instance for the master view object to the Selected list.
Select the master view object from the Selected list as shown in Figure 22-28, select all the operations in the Basic Operations list, and click OK.
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.
In the overview editor for the product application module, click the Java navigation tab and click the link for the Application Module Class.
Add the utility methods shown in Example 22-10 to the application module class. These utility methods enable web service clients to obtain FlexfieldSdoSupport objects to access flexfield information.
Replace Flexfield with the appropriate string for the flexfield that you are working with.
In the getFlexfieldSdoSupport method, replace getDffAM with the name of the getter method for the nested flexfield application module.
Example 22-10 Utility Methods for Flexfield Service Data Object Support
public List<String> getFlexfieldSdoNamespaceAndName(String contextValue) { FlexfieldSdoSupport ss = getFlexfieldSdoSupport(contextValue); if (ss == null) { return null; } return Arrays.asList(ss.getSdoNamespace(), ss.getSdoName()); } public String getFlexfieldTypeSdoPath() { FlexfieldSdoSupport ss = getFlexfieldSdoSupport(null); if (ss == null) { return null; } return ss.getDiscriminatorSdoPath(); } public List<String> getFlexfieldSegmentSdoPaths(String contextValue, List<String> segmentCodes) { FlexfieldSdoSupport ss = getFlexfieldSdoSupport(contextValue); if (ss == null) { return null; } ArrayList r = new ArrayList(segmentCodes.size()); for (String segmentCode: segmentCodes) { r.add(ss.getSegmentSdoPath(segmentCode)); } return r; } public FlexfieldSdoSupport getFlexfieldSdoSupport(String contextValue) { // Set contextValue to null to get the parent (base) // Find the nested flexfield application module instance DFFApplicationModuleImpl am = (DFFApplicationModuleImpl) getDffAM(); return am.getSdoSupport(contextValue); }
In the overview editor for the product application module, click the Service Interface navigation tab for the product application module and click the Edit icon in the Service Interface Custom Methods section.
In the Service Custom Methods dialog, shuttle 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.
You can test the service by adding StringRefAddr elements to the Reference element for the project 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 Section 22.13.1, "How to Expose a Descriptive Flexfield as a Web Service."
Make sure that the BC4J Service Client and BC4J Service Runtime libraries are included in your application project.
To test the web service:
Expand Application Resources > Descriptors > ADF Meta-INF, and open the connections.xml file.
Locate the Reference element for the project application module's service (DFF1MasterApplicationModuleService in this example).
Add the StringRefAddr elements that are shown in bold in Example 22-11 to the Reference element for the project application module's service. Modify the host and port number in the jndiProviderURL entry to point to your WebLogic Server. The port number is typically 7101.
Example 22-11 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>
Run the remote server class for the product application module to deploy the service to the integrated WebLogic server and to manually test the web service.
Note:
The remote server class was generated when you exposed the descriptive flexfield as a web service in Section 22.13.1, "How to Expose a Descriptive Flexfield as a Web Service." This class has a name that ends withServiceImpl.javaOptionally, 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 22-12 shows how to get a data row. The XML payload output of this program is shown in Example 22-13.
Example 22-14 shows how to create a new data row.
Example 22-15 shows how to update an existing data row.
Example 22-12 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 22-13 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 22-14 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 22-15 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();
}
}
...
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 Desktop Integration Developer's Guide for Oracle Application Development Framework 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.
Incorporating a descriptive flexfield as a dynamic component or a single cell on the page.
Creating an Excel workbook to integrate with the descriptive flexfield.
Preparing your Excel workbook to access the column containing the flexfield.
The Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework 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 Table component.
A web page picker popup dialog can be associated with a dynamic column, enabling 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 Table component.
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 Table component, 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, 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 toFalse.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 Form component, 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 and ADF Desktop Integration Excel Workbook:
Configure ADF Desktop Integration with either a dynamic or static column descriptive flexfield.
If using a dynamic column descriptive flexfield where the user can control the context value, handle user-initiated context values changes in the dynamic column descriptive flexfield.
Handle the update or insert of a descriptive flexfield data row.
When you configure the ADF Table component, 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 which 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 Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework.
To make the descriptive flexfield column of the Table component dynamic, set the DynamicColumn property in the TableColumn array of the ADF Table component 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 Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework.
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.
ADF Desktop Integration requires that to use a dynamic column implementation, the structure of the descriptive flexfield 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 user of the workbook, changes are not an issue. However, if the user can control the context value (for example, using an LOV in a "header" form), your application must be able to respond appropriately to update the descriptive flexfield structure.
After the user specifies a context value, you must invoke the worksheet UpSync method to get the new value into the model. Then you can use the ADF Table component Download method to get fresh data with the new descriptive flexfield structure.
Note:
For an insert-only table, theDownload method is undesirable. For these cases, use either the ADF Table component DownloadForInsert method or the Initialize method to enable the Table component to reconfigure to accommodate the new flexfield structure.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 Table component. If you are adding your descriptive flexfield as a static column, you can alternatively use an ADF Read-only Table component. Keep in mind that ADF Read-only Table components support static columns, but not dynamic columns. Popup dialogs support both types.
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. You should 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 of an InputText or OutputText component, then connect the Dialog action to a JSPX page that will display the descriptive flexfield.
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 Oracle Fusion Middleware Desktop Integration Developer's Guide for Oracle Application Development Framework.
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.
To handle update or insert of a data row containing a descriptive flexfield in an ADF Desktop Integration table, you call a custom application module method which 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 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, since this controls the structure of the flexfield.
The following examples demonstrate the code needed to accomplish these tasks. Example 22-16 and Example 22-17 apply to an ADF Desktop Integration implementation with the descriptive flexfield exposed as a static column. Example 22-18 presents the isSegmentDisplayable() method that is used in the other two examples.
Example 22-16 Updating or Inserting a Row with a Descriptive Flexfield Static Column
//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 descriptive flexfield row based on descriptive flexfield view accessor DFFViewRowImpl dffRow = (DFFViewRowImpl)srcRow.getAttribute(mydff_viewaccessor); //Check if single cell value is null if (dffAttributeValue != null && !("").equals(dffAttributeValue)) { //Getting DFF metadata information FlexfieldViewDefImpl dffImpl = (FlexfieldViewDefImpl)dffRow.getFlexfieldViewDef(); String delim = dffImpl.getDelimiter(); //Tokenizing DFF string StringTokenizer token = new StringTokenizer(dffAttributeValue.toString(), delim); while (token.hasMoreTokens()) { prjValues.add(token.nextToken()); } } //Get 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 context dependent DFF case //If context is changed right before upload, 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 22-17 Applying Modified Segment Values to a Cell in a Descriptive Flexfield Static Column
You add this code as an application module method which will be invoked from 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 delimiter information for your DFF FlexfieldViewDefImpl dffImpl = (FlexfieldViewDefImpl)dffRow.getFlexfieldViewDef(); String delim = dffImpl.getDelimiter(); //Get 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 inbetween each segment value // If the segment type is date, trim the time portion // 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 22-18 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;
}
}
}
|
 Copyright © 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|