Configuration Attributes for Fusion Configurator Engine Models

This chapter describes how to set up configuration attributes for Models that use the Fusion Configurator Engine.

This chapter covers the following topics:

• About Configuration Attributes
• Tasks for Adding Configuration Attributes to an FCE Model
• Setting Up Descriptive Flexfields
• Adding Attribute Features
• Associating Attribute Features to Flexfield Segments
• Associating BOM Nodes with Attribute Features
• Defining the Configurator Extension Rule
• Access to Configuration Attribute Data
• Special Considerations
• Maintaining the Configuration Attributes Setup
• Using Configuration Attributes in the Downstream Application

About Configuration Attributes

The term configuration attributes means attributes of a configuration produced by the runtime Oracle Configurator. Attributes are predefined data items that record qualities of something. Configuration attributes record data generated during a particular configuration session for qualities that are not defined in the configuration model.

The use of configuration attributes is a methodology for using certain existing features of Oracle Configurator and host applications to capture and exchange data that is not standard inventory information. This kind of data can be especially valuable for processing by other applications.

The configuration attributes methodology was introduced in a previous release of Oracle Configurator. For more details, examples, and important background on the previous implementation, see Oracle Configurator Methodologies.

Important: This chapter only describes adding configuration attributes to an FCE Model that does not already use them. If you are already using configuration attributes with a model that uses the Original Configurator Engine, and you have converted that Model to use the FCE, and you want to use configuration attributes with the new FCE Model, then you will have to change your setup for the FCE Model to accord with the setup described here. See the Oracle Configurator Release Notes, Release 12.1.1 on the Oracle Support Web site for background on these differences. Your configuration attributes setup on your original Model will continue to operate without change.

The setup for configuration attributes consists of the elements described in the table Elements of the Configuration Attributes Setup.

Elements of the Configuration Attributes Setup

Element	Purpose
A configuration model that includes:
- Imported BOM Model nodes	Configuration attributes describe attributes of these nodes that are not defined in the inventory item.
- Feature nodes	At runtime, values for the configuration attributes are stored in certain specified Features. Features used for this purpose are called attribute Features.
- Properties	Certain specially-named Properties associate BOM Nodes with their corresponding attribute Features. Other specially-named Properties associate the attribute Features with descriptive flexfield segments for a given context. Properties used for this purpose are called attribute Properties.
Descriptive flexfield definitions	Flexfield segments connect attribute Features with columns in CZ_CONFIG_ATTRIBUTES, for a given set of flexfield contexts
CZ_CONFIG_ATTRIBUTES	This table stores the values for the configuration attributes so that they can be read for further processing by downstream applications. This table is called the attribute flexfield table.
Configurator Extension	Turns on runtime attribute processing, which gathers the runtime values from the attribute Features of the Model and writes them to the attribute flexfield table.

An example of how a configuration attribute is set up, and how it is used at runtime, is provided in the figure Overview of Configuration Attributes. The flow of the example is explained in the table Configuration Attributes Flow. The details of this setup are explained in following sections, which refer to the elements in this example.

Overview of Configuration Attributes

Configuration Attributes Flow

Step	Process	Example
1	At runtime, when a configuration is initialized (created or restored), the postConfigInit() method of CZAttributeCX is triggered by a Configurator Extension Rule. This method turns on attribute processing, which collects attribute information on the nodes in the configuration model by searching for specially-named attribute Properties.	FRAME_TYPE is the BOM node that is set up for configuration attributes.
2	Attribute processing searches BOM nodes for attribute Properties with names of the form ATTR_n_PATH.	The attribute Property ATTR_1_PATH is found on the BOM node FRAME_TYPE.
3	Attribute processing searches for the node named by ATTR_n_PATH, under the BOM Model node closest to the node	The value of ATTR_1_PATH is Frame_Size, which indicates that there is an attribute Feature named Frame_Size FRAME_TYPE is a BOM Option Class. The closest BOM Model node is BIKE_FRAME. The node named Frame_Size is found under BIKE_FRAME.
4	On the specified attribute Feature, attribute processing obtains the values of the attribute Properties ATTR_NAME and ATTR_CONTEXT.	The value of ATTR_NAME is Size. The value of ATTR_ CONTEXT is Standard.
5	An end user enters a value for an attribute Feature.	The user enters the value 18 for Frame_Size.
6	When the configuration is saved, the descriptive flexfield tables are queried using the values of ATTR_NAME and ATTR_CONTEXT.	The value of ATTR_NAME is Size. The value of ATTR_ CONTEXT is Standard. These values indicate that the attribute Feature is associated with a descriptive flexfield segment named Size, and a flexfield context of Standard.
7	The values for descriptive flexfield segment and context are used to determine which ATTRIBUTEn column in CZ_CONFIG_ATTRIBUTES is associated with the segment and context.	The flexfield setup indicates that the segment Size, for the context Standard, is associated with column ATTRIBUTE1.
8	The value of the attribute Feature is written to the desired column in CZ_CONFIG_ATTRIBUTES.	The value 18, for the attribute Feature Frame_Size, is written to ATTRIBUTE1.

Tasks for Adding Configuration Attributes to an FCE Model

To set up configuration attributes for an FCE Model, perform the tasks listed in the table Summary of Setup Tasks for Configuration Attributes. For more information about the tasks, refer to the sections cited in the Details column.

Summary of Setup Tasks for Configuration Attributes

Step	Task	Details
1	Set up descriptive flex field contexts and segments.	Setting Up Descriptive Flexfields
2	Add attribute Features to a BOM Model.	Adding Attribute Features
3	Associate the attribute Features to flexfield segments.	Associating Attribute Features to Flexfield Segments
4	Associate BOM nodes to attribute Features.	Associating BOM Nodes with Attribute Features
5	Define the Configurator Extension Rule.	Defining the Configurator Extension Rule

Important: This chapter only describes adding configuration attributes to an FCE Model. If you are already using configuration attributes with a model that uses the Original Configurator Engine, and you have converted that Model to use the FCE, and you want to use configuration attributes with the new FCE Model, then you will have to change your setup for the FCE Model to accord with the setup described here. See the Oracle Configurator Release Notes, Release 12.1.1 on the Oracle Support Web site for background on these differences. Your configuration attributes setup on your original Model will continue to operate without change.

Setting Up Descriptive Flexfields

The configuration attributes methodology uses the existing Oracle Applications feature of descriptive flexfields to connect the set of attributes on a configuration model with a database table that stores the values of those attributes.

• To define the contexts and segments for the flexfields, log into Oracle Applications with the Oracle Application Developer responsibility.

  For conceptual background on descriptive flexfields and contexts, and details on defining them, see the Oracle E-Business Suite Flexfields Guide.

• When you define the contexts for the flexfields, you must create whatever contexts are required by the host application. For all the contexts that you define, use the settings shown in the table Flexfield Settings for All Configuration Attributes Contexts.

  Flexfield Settings for All Configuration Attributes Contexts

  Setting	Value
  Application	Oracle Configurator
  Table Application	Oracle Configurator
  Table Name	CZ_CONFIG_ATTRIBUTES

• When you define the segments for each context, you must specify the ATTRIBUTEn column in CZ_CONFIG_ATTRIBUTES in which that segment’s data will be written. By using different contexts you can use the same column to store attribute data for different attribute Features.

The figure Flexfield Contexts and Segments shows the relationship of flexfield contexts and their segments to the Properties of an attribute Feature. Compare this figure to the figure Association of Attribute Features to Flexfields.

Flexfield Contexts and Segments

Adding Attribute Features

The structure of a BOM Model does not have a location for storing configuration attributes data. To create such locations, you must add structure to imported BOM Models, in Oracle Configurator Developer. In the configuration attributes methodology, the added structure takes the form of attribute Features. Attribute Features are not a new type of Feature. The term attribute Feature simply means a Feature that is used to contain the data for a configuration attribute.

The figure Imported BOM Model shows the structure of the imported BOM Model for this example, before addition of attribute features.

Imported BOM Model

This imported BOM structure does not have locations for storing certain pieces of data that you might want to capture during a configuration session for ordering a bicycle, such as:

• the color of the BIKE_FRAME being ordered

• the frame size of the BIKE_FRAME being ordered

• the name of the customer placing the BIKE_ORDER

• whether that customer elected a service plan for the BIKE_ORDER

To provide locations for entering runtime values for configuration attributes for this Model, create the following Feature nodes:

• Color: to capture the color of the BIKE_FRAME being ordered

• Frame_Size: to capture the frame size of the BIKE_FRAME being ordered

• Customer: to capture the name of the customer placing the BIKE_ORDER

• Service_Plan: to capture whether that customer elected a service plan for the BIKE_ORDER

The figure Model with Attribute Features shows the structure of the modified Model for this example, after the addition of the attribute Features listed in this section. Compare this figure to the figure Imported BOM Model, and to step 5 in the table Configuration Attributes Flow.

Model with Attribute Features

Attribute Features work in conjunction with descriptive flexfield segments (which are described in Setting Up Descriptive Flexfields). The value provided at runtime for an attribute Feature is stored, when the configuration is saved, in the attribute flexfield table CZ_CONFIG_ATTRIBUTES in the column specified by the associated flexfield segment’s definitition.

For more information about defining Features, see the Oracle Configurator Developer User’s Guide.

Associating Attribute Features to Flexfield Segments

To create associations between attribute Features and their corresponding descriptive flexfield contexts and segments, you must add attribute Properties to the Features, in Oracle Configurator Developer.

• To associate an attribute Feature to the corresponding descriptive flexfield segment, define a Property of type Text, named ATTR_NAME. The value of the Property must be the name of the corresponding segment.

• To associate an attribute Feature to the corresponding descriptive flexfield context, define a Property of type Text, named ATTR_CONTEXT. The value of the Property must be the name of the corresponding context.

The figure Association of Attribute Features to Flexfields shows how the attribute Properties ATTR_CONTEXT and ATTR_NAME define associations between attribute Features and their corresponding descriptive flexfield contexts and segments. Compare this figure to the figure Flexfield Contexts and Segments, and to steps 4 and 6 in the table Configuration Attributes Flow.

Association of Attribute Features to Flexfields

For more information about defining Properties, see the Oracle Configurator Developer User’s Guide.

Associating BOM Nodes with Attribute Features

To create associations between BOM nodes and the attribute Features that store their configuration attribute values, you must add attribute Properties to the BOM nodes, in Oracle Configurator Developer.

• The Property must be named ATTR_n_PATH, where n is an integer that makes the name unique within the scope of the current node.

• The value of the Property must be the node path to the attribute Feature, starting from the BOM Model node that is nearest to the node with the ATTR_n_PATH Property.

  If the node with the path property is a BOM Model, then that nearest BOM Model node is itself. If not, then the nearest BOM Model node is found by recursively looking upward in the Model tree until the nearest BOM Model node is found.

• The nodes in the node path are delimited by a dot (‘.’).

• You can create multiple ATTR_n_PATH Properties for the same node, with different values of n, to assign multiple attribute Features to the node. This means that you can assign multiple configuration attributes to the same inventory Item.

• You can use the same ATTR_n_PATH name in different nodes without conflict. (In ordinary practice, you would probably start by using ATTR_1_PATH each time you created a Property on a different node.)

• See steps 2 and 3 in the table Configuration Attributes Flow for an example of an ATTR_n_PATH Property and how it is used by attribute processing.

The figure Association of BOM Nodes to Attribute Features shows how the attribute Property ATTR_n_PATH is defined to associate BOM nodes with attribute Features. Compare this figure to steps 2 and 3 in the table Configuration Attributes Flow.

Association of BOM Nodes to Attribute Features

For more information about defining Properties, see the Oracle Configurator Developer User’s Guide.

Defining the Configurator Extension Rule

To provide attribute processing, you must define a Configurator Extension Rule as described in this section.

To ensure that attribute processing is turned on for the entire configuration session, and that processing is performed on all nodes, the event binding for the Rule must specify the Event as postConfigInit, which is the first event raised in a session.

The Java class required for this rule, CZAttributeCX, is already installed in the class path used by the runtime Oracle Configurator. Consequently, you do not have to perform many of the steps ordinarily required for providing a Java class for a Configurator Extension (compiling Java source code, placing compiled classes in a Java class archive file, creating a Configurator Extension Archive, and adding it to the Model’s archive path). Instead, you can just enter its fully-qualified class name in the Rule definition.

Procedure

1. In Oracle Configurator Developer, create a Configurator Extension Rule.

2. Choose the options listed in the following table:

   Option	Choice
   Model Node	The root node of the Model. (In the example shown here, the root node is BIKE_ORDER.)
   Java Class	oracle.apps.cz.cx.CZAttributeCX (Enter this fully-qualified class name directly as shown. Do not select Choose Class.)
   Java Class Instantiation	With Model Node Instance

3. Create an event binding for the Configurator Extension Rule, choosing the options listed in the following table:

   Option	Choice
   Event	postConfigInit
   Event Scope	Global (This scope is the only choice for this event.)
   Method	postConfigInit(oracle.apps.cz.core.IRuntimeNode)

4. Create an argument binding for the event binding, choosing the options listed in the following table:

   Option	Choice
   Argument Type	oracle.apps.cz.core.IRuntimeNode
   Argument Specification	System Parameter
   Binding	<BaseNodeOfRule>

5. Generate logic for your Model, to reflect the addition of the Configurator Extension Rule.

For more information about defining Configurator Extension Rules, see the Oracle Configurator Developer User’s Guide.

Access to Configuration Attribute Data

The goal of the configuration attributes methodology is to place attribute data in a database table where it can be used by downstream applications. See the following sections for details:

• About the CZ_CONFIG_ATTRIBUTES Table

• Writing Data to the CZ_CONFIG_ATTRIBUTES Table

• Reading Data from the CZ_CONFIG_ATTRIBUTES Table

About the CZ_CONFIG_ATTRIBUTES Table

The attribute flexfield table, CZ_CONFIG_ATTRIBUTES, is used as the intermediate store of configuration attribute data between Oracle Configurator and a host application.

The CZ_CONFIG_ATTRIBUTES Table

Column Name	Null?	PK?	Type	Comments
CONFIG_HDR_ID	N	Y	NUMBER(9)	Configuration header ID
CONFIG_REV_NBR	N	Y	NUMBER(9)	Configuration revision number
CONFIG_ITEM_ID	N	Y	NUMBER(9)	Configuration item ID
ATTRIBUTE_CATEGORY	N	Y	VARCHAR2(30)	Name of flexfield context
ATTRIBUTE1	N	N	VARCHAR2(4000)	Flexfield segment value for the specified context
ATTRIBUTE2	N	N	VARCHAR2(4000)	Flexfield segment value for the specified context
...	...	...	...	...
ATTRIBUTE30	N	N	VARCHAR2(4000)	Flexfield segment value for the specified context

The columns CONFIG_HDR_ID, CONFIG_REV_NBR, CONFIG_ITEM_ID and ATTRIBUTE_CATEGORY constitute the primary key for CZ_CONFIG_ ATTRIBUTES.

All of the columns ATTRIBUTE1 through ATTRIBUTE30 are defined identically, and the columns between ATTRIBUTE2 and ATTRIBUTE30 have been omitted from the table The CZ_CONFIG_ATTRIBUTES Table for brevity. The standard columns such as LAST_UPDATE_DATE have also been omitted for brevity.

For information about the Oracle Configurator schema, see the Oracle Configurator Implementation Guide. For technical details about CZ_CONFIG_ATTRIBUTES, CZ_ CONFIG_EXT_ATTRIBUTES, and other tables, see the Oracle Integration Repository.

Writing Data to the CZ_CONFIG_ATTRIBUTES Table

When attribute processing is in effect, and a runtime configuration is saved, then the Core Java API for Oracle Configurator (oracle.apps.cz.core) writes the accumulated attribute data to the attribute flexfield table CZ_CONFIG_ATTRIBUTES, using the flexfield associations for guidance on which columns to write into.

When a runtime configuration is saved, the API method that is invoked takes a list of BOM nodes that have associated configuration attributes. For each BOM node in the list, the attributes are sorted by flexfield context, which corresponds to the ATTRIBUTE_CATEGORY column of the table. Then for each attribute category for that BOM node, a row is written to the table. The row contains all the attribute values for that node and context. The flex field tables (FND_DESCR_FLEX_COLUMN_USAGES, FND_DESCRIPTIVE_FLEXS and FND_APPLICATION) are queried to determine the mapping between attribute-context and flex field column.

Reading Data from the CZ_CONFIG_ATTRIBUTES Table

When you need to obtain configuration attribute data from the CZ_CONFIG_ATTRIBUTES table, you can use a SQL query like the one shown in the example Query for Attribute Data. The results of this query are shown in the figure Configuration Attribute Data.

You must write any custom procedures required to provide configuration attribute data to downstream applications.

To run the query shown here, replace the values for a.CONFIG_HDR_ID and a.CONFIG_REV_NBR with the Configuration Header ID and Configuration Revision values returned when a configuration session ends and the configuration has been saved. When you use the Test Model function of Oracle Configurator Developer, these values are displayed on the Confirmation page. When you save a configuration by other means (for instance, from a host application), then the Configuration Header ID and Configuration Revision values are written to the config_header_id and config_rev_nbr elements of the XML termination message. See the Oracle Configurator Implementation Guide for information about the termination message.

Query for Attribute Data

SELECT
  a.CONFIG_HDR_ID,
  a.CONFIG_REV_NBR,
  a.CONFIG_ITEM_ID, 
  i.PS_NODE_NAME,
  a.ATTRIBUTE_CATEGORY,
  a.ATTRIBUTE1,
  a.ATTRIBUTE2,
  a.ATTRIBUTE3,
  a.ATTRIBUTE10
FROM 
  CZ_CONFIG_ATTRIBUTES a, CZ_CONFIG_ITEMS i
WHERE
  a.CONFIG_HDR_ID = 4175522  -- from saved configuration 
AND
  a.CONFIG_REV_NBR = 1   -- from saved configuration
AND 
  a.CONFIG_ITEM_ID = i.CONFIG_ITEM_ID
AND 
  a.CONFIG_HDR_ID = i.CONFIG_HDR_ID
AND 
  a.CONFIG_REV_NBR = i.CONFIG_REV_NBR
ORDER BY 
  a.CONFIG_ITEM_ID

-- ---------------------------------------------------
set linesize 400

set headsep on
column CONFIG_HDR_ID heading 'CONFIG|_HDR_ID'
column CONFIG_REV_NBR heading 'CONFIG|_REV_NBR'
column CONFIG_ITEM_ID heading 'CONFIG|_ITEM_ID'
column ATTRIBUTE_CATEGORY heading 'ATTRIBUTE|_CATEGORY'

column PS_NODE_NAME format a16
column ATTRIBUTE_CATEGORY format a24
column ATTRIBUTE1 format a12
column ATTRIBUTE2 format a12
column ATTRIBUTE3 format a12
/

The output in the figure Configuration Attribute Data shows the result of running the query in the example Query for Attribute Data.

Configuration Attribute Data

Special Considerations

This section covers some important considerations that may affect your implementation of the configuration attributes methodology.

• Referenced Models

  If your Model includes child Models that are connected through References (as is the case with most imported BOM Models), then attribute processing traverses the entire structure of the Model, collecting configuration attribute data from any attribute Properties whose names conform to the conventions described in this chapter.

• Location of Attribute Features

  You must give careful thought to where you create attribute Features. An attribute Feature can be located anywhere in a Model, provided that the location is a node path that can be specified by the Property ATTR_n_PATH. Consequently, the node path to an attribute Feature must be specified as relative to the Model that contains the Item.

  Attribute processing first finds the node that is the root of the entire configuration model, and then searches from there for Properties whose names conform to the conventions described in this chapter.

  Because attribute processing can find Features in child Models that are connected through References, it is possible to assign a configuration attribute value to an Item in a parent Model by pointing (with the Property ATTR_n_PATH) to an attribute Feature in a referenced child Model. Such a node path must include the names of any child Models between the Model that contains the Item and the attribute Feature. However, a node path that you can express as a Text Property value can only point down the tree of Models, not upwards. Consequently, it is not possible to point to an attribute Feature in a parent Model, and therefore you cannot assign a configuration attribute value from a parent Model to an Item in a child Model.

  Here is an illustration, using the example Model cited elsewhere in this chapter and shown in the figure Association of BOM Nodes to Attribute Features. When the configuration attribute is an attribute (Size) of a BOM Option Class (FRAME_TYPE), then the attribute Feature (Frame_Size) must be a child of that BOM Option Class's parent model (BIKE_FRAME), which is the nearest BOM Model node. The path from that BOM Model (from BIKE_FRAME to Frame_Size) cannot be up, only down (as it is). The node path generally cannot traverse child references, unless the reference is a required single instance.

  To summarize: parent Models can use attribute Features defined in referenced child Models; child Models cannot use attribute Features defined in parent Models.

  It follows from the preceding facts that if you intend to use a referenced child Model without the parent Model, then you must ensure that it contains all the attribute Features that are employed as the configuration attributes on the Items in that Model.

• Multiple Component Instances in the Node Path

  The node path to an attribute Feature, which is specified by the Property ATTR_n_PATH, cannot include any Components that can be instantiated multiple times. (Such a Component is one that has its Instances set to a Maximum greater than 1, so that more than one runtime instance of the Component can be created and configured.) The existence of multiple instances of a Component in a node path makes the path ambiguous. Consequently, you cannot place any attribute Features inside such a Component, because attribute processing cannot resolve the correct path to that attribute Feature. This restriction also applies to Components whose instantiability is Optional Single Instance.

• Reusing an Attribute Value for Multiple Items

  It may be required that more than one Item needs the same configuration attribute value. You can accomplish this by making the Items point to the same instance of the attribute Feature that contains that value. You do this by setting the same value for the attribute Property ATTR_n_PATH in each Item.

• Required Items

  Configuration attributes cannot be defined for required Standard Items in a BOM Model, because such Items are not configurable, and consequently are not imported when you import the BOM Model into Oracle Configurator Developer to define a configuration model. (See the Oracle Configurator Implementation Guide for details about importing.)

• Effects of Auto-Complete and Adjust Mode

  After a successful Auto-Complete operation, any values for attribute Features that were bound by the results of Auto-Complete are converted to Auto-Complete Decisions (ACDs). (ACDs keep track of the selections made by Auto-Complete itself. ACDs are retained during Adjust Mode, and are re-applied when the user subsequently chooses Finish or Auto-Complete.) This functionality enables configuration attributes to capture values for all attribute Features that you consider to be output of the configuration, not only those explicitly selected by the end user.

Maintaining the Configuration Attributes Setup

You must manually update your Model in Oracle Configurator Developer if the following are changed:

• The flexfield definitions in Oracle Applications. Changes to the flexfield definitions might include changes to context or attribute column assignments.

• The BOM (in Oracle Bills of Materials) that is the basis for your imported Model. Changes to the Bill of Material might include the addition of an Item that should have configuration attributes.

If the BOM changes, you can reflect the changes by refreshing your Model. See the Oracle Configurator Implementation Guide for details on refreshing Models. If you refresh your Model, you may need to make changes in your attribute Features and Properties.

Using Configuration Attributes in the Downstream Application

For suggestions about using configuration attributes in a downstream application, see the following sections in Oracle Configurator Methodologies:

• "Using Configuration Attributes in the Downstream Application"

• "Using Output Data in Downstream Applications"

• "Linking Configuration Attributes to Flexfields"

• "Downstream User Interfaces"