This chapter includes the following sections:
Different organizations within a single company often need to use different sets of reference data to serve the same purpose. For example, the job codes for one country might be different from the job codes for another country. Different Oracle Fusion Applications customers should be able to make their own decisions about how to define the job codes, and be able to define a separate set for each organizational section of the enterprise. They should also be able to define a common set or sets and instruct the system which set is required by which organizations. For example, job codes for software engineers might be MTS, SMTS, PMTS; job codes for managers might be M1, M2, M3. SetIDs enable them to accomplish this easily.
For information about set-enabling lookups, see Implementing Lookups.
SetID Implementation
After you have completed the development process as discussed in this chapter, and delivered your application with the ability to use set-enabled reference data, application implementers and administrators must then be able to define and maintain reference data sets and set assignments that are appropriate to the organization which will use the application. They can accomplish these tasks using the Manage Reference Data Sets and Manage Reference Data Set Assignments applications, respectively.
You make these setup applications available to implementers and administrators by incorporating their task flows into Oracle Functional Setup Manager. For more information, see About Integrating SetID Task Flows into .
For information about implementing your specific product family, do the following:
Access the Oracle Fusion Applications library.
See the Implementing Common Features guides for your product family.
SetIDs enable you to share a set of reference data across many organizations. Sharing reference data is a method of limiting the set of available values to those that are appropriate for a validated attribute. Some benefits of this include:
The list of values for a field in a user interface is reduced
An attribute passed into an API is validated against the limited set of values
The end goal is to save customers some effort in maintaining reference data by enabling it to be shared between different parts of the organization that implements applications. Reference data should not need to be maintained in multiple places at multiple times. Reference data is data in tables that you do not regard as transactional and high volume; for example, payment terms that can be used on a customer invoice.
By dividing the reference data into partitions appropriate to the organizational entities that will use the data, setIDs enable you to share control table information and processing options among business units. The goal is to minimize redundant data and system maintenance tasks. For example, you can define a group of common job codes that are shared between several business units. Each business unit that shares the job codes is assigned the same setID for that record group.
SetIDs can be thought of as a striping technology to partition referenced data. All shared reference tables can be striped with a setID column to enable partitions (or sets). This does not require you to change the tables' primary keys.
With partitioning, a customer can choose to have reference data sets specific to each organizational unit mapped one-to-one, or have several different organizational units use the same set of reference data. Customers, rather than development, will have the choice in determining what level of sharing or exclusivity they would like to maintain in the reference data.
A setID is the means by which applications can filter reference data into subsets when they are referenced by different transactional entities. The filtering is driven, indirectly, by contextual values available in the referring transactional entity.
Use of the shared data partitions is facilitated by a context setting called the determinant, which is usually a column on the referring transactional entity. The purpose of the determinant is to identify an organizational subset; you use it to specify which reference data is valid for use in a given business context. The determinant is the value of a transactional column that is one of several designated determinant types. If at least one column of the transactional table is a setID determinant type, data sharing may make sense for the transaction.
For example, different business units may use the same office supply vendor, but have different requirements for which supplies can be purchased. The determinant type and value provide part of the criteria for selecting the appropriate office supply reference data set.
In addition to the presence of a determinant on the transactional entity, the data that you want to reference must be set-enabled as described later in this documentation.
The setID determinant type can be one of the following existing fields:
Asset Book — A book that contains assets belonging to a business unit or ledger. It holds information about the asset's acquisition, depreciation, and retirement. An asset may be assigned to one or more books; for example, the corporate, tax and budget books.
Business Unit — This roughly corresponds to a department or organization. For example, Virgin might have an airline, a store, and a recording label as different business units.
Cost Organization — A cost organization groups inventory organizations within a legal entity to achieve the following:
Establish the cost accounting policies for the inventory organizations.
Support cost accounting reporting.
Allow the definition of defaults.
Allow multiple inventory organizations to share cost calculation.
Restrict role access to costing data.
Cost organization will likely map into a company's enterprise structure as a cost department.
Project Unit — A logical organization within a company created to ensure and enforce consistent project management practices.
Reference Data Set — For cases where shared reference data has references to other shared reference entities.
Some Criteria for Selecting a Determinant Type
To help decide what determinant type to use for a given application, consider the following:
If you cannot change the reference data for different parts of a deploying enterprise, the reference data is global and partitioning is not required.
Examples of data suitable for partitioning include (but are not limited to) units of measure, currency codes, country codes, or anything else governed by a standard.
If the values for the reference data will be decided by the general manager, the best reference data set determinant is likely to be the Business Unit.
For more information about setID determinant types, see How to Annotate Transactional Entity Objects for SetID.
SetID Machinery is the collection of Applications Core Technology software elements that act in concert to facilitate the use of setIDs to partition, access and maintain reference data. At a high level, the machinery is comprised of:
SetID configuration tables
SetID metadata for business objects and extensions to ADF Business Components middleware
SetID design-time extensions
SetID summary tables
The following sections introduce the elements of setID machinery and the ways in which they can be used to implement data sharing.
There are three setID partitioning patterns. Choose one of these patterns based on your business requirements:
Row striping (ROWSTRIPE
) — This is the simplest pattern, and the default. In this pattern the SET_ID column is just a striping column, and is not part of the set of unique keys for the table. You can filter as follows:
WHERE SET_ID = :1
Row striping with common rows (COMMON
) — This is the same as the row striping pattern, with the addition of a COMMON partition. You filter as follows:
WHERE SET_ID IN (:1, 0)
Note:
The set with setID of 0
is seeded as the common set. This set will be available for assignment only if you select Row Striping With Common Rows for the reference entity.
SetID subscription (SUBSCRIPTION
) — The drawback of the first two patterns is that if reference data must be in two different partitions (other than the common one), it has to be copied and placed in both sets. To avoid that, a setID subscription table can be introduced and used to list which sets include each row. This will allow the same reference data to be in two different sets without the need to copy the data for each set. You join your reference entity with the setID subscription table and filter as follows:
SET_ID: WHERE PARENT.PK1=SUBSCRIPTION.PK1 AND SUBSCRIPTION.SET_ID = :1
For more information about partitioning patterns, see How to Annotate Reference Entity Objects for Sharing.
In addition to tables, other sources of reference data such as lookup types and views can also be shared using setIDs. These are all generically referred to as reference entities. Reference entities are generally considered to be setup data, and they may be implementing business policies and legal rules. Reference entities in your application are grouped into logical units called reference groups, based on the functional area and the partitioning requirements they have in common. For example, all tables and views that define Sales Order Type details might be part of the same reference group.
Figure 8-1 illustrates an example of a Worker Assignment transaction table with two set-enabled references: a reference to Salary Codes with partitions determined by Business Unit, and another reference to Labor Agreement with partitions determined by Cost Organization.
Figure 8-1 Example of a Table with Two SetID Reference Groups
There are five types of set configuration tables:
Sets
Reference groups
SetID assignments
Reference entities
Sets Table
The sets table, FND_SETID_SETS, lists all of the sets defined for Oracle Applications, plus any new sets that you define. It includes the columns SET_ID and SET_NAME, which enable you to select the proper SET_CODE.
Sets listed in this table include:
The two default seeded sets, COMMON and ENTERPRISE.
Default sets that map to existing transaction data, created as an upgrade to Applications Unlimited.
New sets created by customers, to implement set-enabled reference entities specific to their organizations.
Reference Groups Table
The reference groups table, FND_SETID_REFERENCE_GROUPS_B, captures the default determinant type for all reference entities in each group. This table uses the primary key of REFERENCE_GROUP_NAME. It also includes the APPLICATION_ID column, which is used for filtering and managing ownership.
The available reference groups defined in the reference groups table will be populated before you start creating entity objects. Reference group definitions are owned by the application that owns the reference entities in that group. Application development teams are ultimately responsible for defining and delivering reference groups.
Note:
Only reference entities that might be referenced as setID targets need to be captured here; this is not intended to be an exhaustive inventory of all tables in the applications. For more information about reference groups, see About Reference Groups.
SetID Assignments Table
A transactional entity may have multiple sets of reference data that are treated in the same manner. For this reason, reference data sets are assigned to a reference group, then the setID assignment is configured for each determinant value, determinant type, and reference group.
The setID assignments table, FND_SETID_ASSIGNMENTS, records which set to use in every reference table for every determinant value. It is a SQL-joinable entity that can be used to convert available context information into a setIDentifier suitable for filtering rows from referenced entities. The context information serves as the table's primary keys:
REFERENCE_GROUP_NAME
DETERMINANT_TYPE
DETERMINANT_VALUE
Based on these keys, you can determine a setID.
Note:
Although development may seed this table with default values, it will be accessed by customers to implement set-enabled reference entities specific to their organizations.
Reference Entities Table
The reference entities table, FND_SETID_REFERENCE_ENTITIES, contains the list of all setID enabled non-lookup reference entities. The SET_ID_PATTERN column indicates which setID pattern is being used by each reference entity. If the value of this field is SUBSCRIBE
(setID subscription), the column SET_ID_CHILD_TABLE will be populated with the setID subscription table name.
Note:
For customers, this table is read-only.
The setID PL/SQL utilities are APIs that include the following packages:
Fnd_setid_sets_pkg package
This package contains table handlers for fnd_setid_sets
table.
Fnd_setid_assignments package
This package contains table handlers for fnd_setid_assignments
table.
Fnd_setid_reference_groups package
This package contains table handlers for fnd_setid_reference_groups
table.
Fnd_setid_ref_entities_pkg package
This package contains table handlers for fnd_setid_reference_entities
table.
Fnd_setid_set_groups package
This package contains table handlers for fnd_setid_set_groups
and fnd_setid_set_group_members
tables.
Fnd_setid_utility package
This package contains the following utilities:
isValid
/** * Returns true if the given parameters are valid, false if not. * * @param referenceGroupName The reference group name * @param setIdDeterminantType The determinant type which could be: * BU, RR, LE... * @param setIdDeterminantValue The determinant value. * @param setId The setid value. * @return true or false. */ function isValid(X_REFERENCE_GROUP_NAME in varchar2, X_DETERMINANT_TYPE in varchar2, X_DETERMINANT_VALUE in varchar2, X_SET_ID in number) return boolean;
getSetId
/** * Returns the set ID corresponding to the specified determinant value, type, * and reference group name. This method implements an LRU cache to speed * up the lookup. * * @param setIdDeterminantValue The determinant value * @param setIdDeterminantType The determinant type which could be: * BU, RR, LE... * @param referenceGroupName the reference group name. * @return the corresponding set ID value. */ function getSetId(X_REFERENCE_GROUP_NAME in varchar2, X_DETERMINANT_TYPE in varchar2, X_DETERMINANT_VALUE in varchar2) return number;
getReferenceGroupName
/** * Returns the reference group name based on a given reference entity name. * * @param referenceEntityName The name of the table to obtain * the reference group for * @return the corresponding reference group name */ function getReferenceGroupName(X_REFERENCE_ENTITY_NAME in varchar2) return varchar2;
isValidSet
/** * Returns true if the set ID exists in the FND_SETID_SETS table, * false if not * * @param setId The setId value * @return Boolean */ function isValidSet(X_SET_ID in number) return Boolean;
You define the following information to implement shared (that is, set-enabled) reference entities:
On the reference entities to be shared:
You provide the shared reference entity group name.
You specify which setID pattern to use: row striping, row striping with common rows, or setID subscription.
In the case of the setID subscription pattern, you specify the subscription table name.
You make sure the attribute corresponding to setID is named SetId
, and specify the determinant type as SET
.
You make sure that any view objects built on the reference entity include the SetId
attribute.
For more information about setID partitioning patterns, see About Partitioning Patterns.
On the transactional entities that will use the shared reference data:
You build entity associations to all shared reference entities.
You specify which attributes are determinants by specifying the determinant type.
On foreign keys that point to shared reference entities, you indicate which determinant attribute drives the set of that reference entity.
Before you begin:
Following are the activities that you should complete before you engage in set-enabling references or lookups:
Determine which reference entities you want to partition for sharing, and set-enable them by adding a SET_ID column.
Generate ADF Business Components entity objects for your set-enabled reference entities and transactional entities. Make sure that your entity objects extend from Oracle Applications base classes (if available) under oracle.apps.fnd.applcore.oaext.model.
For more information, see the "Creating a Business Domain Layer Using Entity Objects" chapter in the Developing Fusion Web Applications with Oracle Application Development Framework.
Generate ADF Business Components entity associations for all of your entity objects.
The following setID metadata will be saved in ADF Business Components metadata as properties:
The reference group name of reference entities.
The setID pattern used by each shared reference entity.
The determinant attributes and their types in a transactional entity.
The determinant on the transactional entity that controls the setID of a shared reference entity.
The setID-related database tables and views should be available as described in About Set Configuration Tables.
Ensure that setID seed metadata has been configured as follows:
The Reference Groups have been defined by teams and approved through the SetID Design Intent Repository process, then seeded in the standard reference groups table.
All set-enabled lookup types have been identified and approved through the SetID Design Intent Repository process, and then properly seeded in the standard lookup types table.
For more information, see Understanding SetID Machinery.
Note:
These annotations are required only for set-enabled non-lookup reference entities. Lookup references and set-enabled lookup references use a predefined lookups pattern; the reference group name is retrieved directly from database by the lookup code and the view application ID that are set on the foreign key reference of the transactional reference.
After building an entity object for a shared reference entity, you annotate the entity object.
To annotate the reference entity object, do the following:
After building an entity object for a transactional entity, you must create entity associations for all foreign references, including FND lookups. Because SET_ID must not be part of the primary key for any shared reference table (except FND_LOOKUP_VALUES), there is nothing unusual about associations for shared references.
Follow these guidelines when creating the associations:
Make sure a destination accessor is generated for the association. ADF Business Components will not honor the association if you do not generate a destination accessor.
Because these reference entities are non-composite, you should not generate source accessors.
After you create entity associations for foreign references, you annotate the transactional entity object.
To annotate the transactional entity object, do the following:
Create a view accessor from the transaction entity to the reference entity.
The key exists validator will include the mapping of the foreign key attributes in the transactional entity to the corresponding attributes in the reference view accessor.
Caution:
If an attribute in your transactional entity was defined with null
values allowed, the validator that you create will skip that attribute, and the end user will receive no indication of any problem. To ensure that the attribute is validated, you must edit the attribute and select the Mandatory checkbox in the attribute properties.
To define a keys exists validator, do the following:
To create a transient setID attribute, do the following:
Every application registers task flows with a product called Oracle Fusion Functional Setup Manager. Functional Setup Manager provides a single, unified user interface that enables implementers and administrators to configure all multiple applications by defining custom configuration templates or tasks based on their business needs.
The Functional Setup Manager UI enables customers and implementers to select the business processes or products that they want to implement. For example, an HR application can register setup activities like "Create Employees" and "Manage Employee Tree Structure" with Functional Setup Manager.
There is an application task flow for managing reference data sets, and one for managing reference data set assignments. To make these task flows available to application developers, implementers or administrators, you can register the appropriate task flow with Functional Setup Manager, using the parameters listed for each task flow in Table 8-2.
Table 8-2 SetID Task Flows and Parameters
Task Flow Name | Task Flow XML | Parameters Passed | Behavior |
---|---|---|---|
Manage Reference Data Sets |
/WEB-INF/oracle/apps/fnd/applcore/setid/publicUi/flow/ManageSetIdSetsTF.xml#ManageSetIdSetsTF |
To optionally specify a page heading for the task flow:
pageTitle='titlestring'
|
This task flow enables you to create and update reference data sets (setIDs and codes). |
Manage Reference Data Set Assignments |
/WEB-INF/oracle/apps/fnd/applcore/setid/publicUi/flow/ManageSetIdAssignmentsTF.xml#ManageSetIdAssignmentsTF |
To invoke the task flow:
determinantType=type
To optionally restrict the page to assignments for a single reference group:
referenceGroupName=name
To optionally specify a page heading for the task flow:
pageTitle='titlestring'
|
This task flow enables you to manage reference data set assignments for a particular determinant type. |
For information about implementing your specific product family, do the following:
Access the Oracle Fusion Applications Library (http://www.oracle.com/technetwork/documentation/fusion-apps-doc-1508435.html
).
See the Implementing Common Features guides for your product family.