| Oracle® Fusion Applications Developer's Guide 11g Release 7 (11.1.7) Part Number E15524-08 |
|
|
PDF · Mobi · ePub |
| Oracle® Fusion Applications Developer's Guide 11g Release 7 (11.1.7) Part Number E15524-08 |
|
|
PDF · Mobi · ePub |
This chapter discusses the Seed Data Loader and using it from within Oracle JDeveloper.
This chapter includes the following sections:
Application Seed Data is the essential data to enable Oracle Fusion applications. Some examples include static lists of values, functional or error messages and lookup values. Seed data is generally static in nature, although it is possible for customers to customize some seed data values after delivery. Any non-transactional data values loaded into a database at customer delivery time can be considered seed data.
Seed data is extracted from Oracle development databases at design time into external files. These files are delivered to the customer and uploaded to the customer's database. Seed data can be delivered and installed at any point in the application lifecycle, such as for a new installation, a major or minor release upgrade, or a patch/change delivery.
Applications that manage seed data need to have a certain amount of knowledge about the seed data. This is so that data to be recreated on the target database is loaded to the correct tables, while preserving referential integrity. This seed data knowledge, or seed meta-data, also must be delivered in some form along with the extracted seed data files. This meta-data drives how the data is extracted and uploaded.
The Seed Data Utility, which runs only under JDeveloper, will provide data extraction from the development instances of Oracle Fusion applications. It will also load the extracted data to the customer database instances of Oracle Fusion applications, by integrating with Oracle Fusion Applications Patch Manager.
Note:
Each entity type, such as Profile and Messages, will have its own dedicated utility. See Table 56-1, "Available Seed Data Loaders".
The Seed Data Extract and Upload processes are run directly from the Seed Data-configured Oracle Application Development Framework (Oracle ADF) Business Components Application Modules. The Seed Data Configuration, Extract, and Upload processes are all run from within JDeveloper, the same development environment in which the Business Object components are defined.
The Seed Data Framework is delivered as a plug-in extension to the JDeveloper environment. The Seed Data Framework is installed by default; there are no other installation or setup steps to perform to begin using the Seed Data Framework tasks. There are support libraries that need to be present in the Business Component project class path before running the Seed Data tasks See Section 56.2.2, "How to Set Up the Seed Data Environment".
Available Seed Data Loaders
The loaders and view objects listed in Table 56-1 are supported.
Legend
Loader: Location of a seed loader-enabled application module. Assume a prefix of oracle.apps.fnd.applcore.
VO: Driving view object.
Is the Module Striped?: Does this view object require a module argument?
Table 56-1 Available Seed Data Loaders
| Loader | View Object | Is the Module Striped? |
|---|---|---|
|
|
FndDocumentEntitiesVL |
N |
|
|
FndDocumentCategoriesVL |
Y |
|
Note: Before running this loader, you need to run the first two loaders listed in this table that have the FndDocumentEntitiesVL and the FndDocumentCategoriesVL view objects. |
FndDocCategoriesToEntitiesVO |
N |
|
|
FndMenus |
Y |
|
|
FndGrants |
Y |
|
|
FndObjects |
Y |
|
|
FndFormFunctions |
Y |
|
|
There are four separate VOs for this, one for each determinant type:
Use the loader appropriate for the determinant type of your sequence, or all four if you want to download all document sequences for all determinant types. |
Y |
|
|
DocSequenceCategories |
Y |
|
|
DocSequenceAudit |
N |
|
|
DocSequenceUsers |
N |
|
|
Category |
N |
|
|
DescriptiveFlexfield |
Y |
|
|
DescriptiveFlexfieldSecondaryUsage |
Y |
|
|
KeyFlexfield |
Y |
|
|
KeyFlexfieldSecondaryTableUsage |
Y |
|
|
ValueSet |
Y |
|
|
LookupView1 |
Y |
|
|
StandardLookupType1 |
Y |
|
|
CommonLookupType1 |
Y |
|
|
SetIdLookupType1 |
Y |
|
|
Message |
Y |
|
|
Currency |
N |
|
|
IsoLanguage |
N |
|
|
Language |
N |
|
|
NaturalLanguage |
N |
|
|
Territory |
N |
|
|
Timezone |
N |
|
|
ProfileCategory |
Y |
|
|
ProfileHierarchy |
N |
|
|
ProfileLevel |
N |
|
|
ProfileOption |
Y |
|
|
Industry |
N |
|
|
SetIdSet |
N |
|
|
SetIdSummary |
Y |
|
|
There are five separate VOs for this, one for each determinant type:
Use the loader appropriate for the determinant type of your sequence, or all five if you want to download all document sequences for all determinant types. |
N |
|
|
SetIdReferenceGroup |
Y |
|
|
FndTreeStructure |
Y |
|
|
ApplTaxonomyVO |
Special case - all the data extracted into a single file. |
|
|
ApplTaxonomyHierarchyVO |
Special case - all the data extracted into a single file |
|
|
ApplTaxonomyPVO |
|
|
|
ApplTaxonomySeedDataVO |
|
|
|
ApplTaxonomySeedDataPVO |
|
|
|
ApplTaxonomyComponentsVO |
Y |
|
|
ApplTaxonomyNodeComponentsVO |
Y |
|
|
FndTree |
N |
|
|
FndDiagTag |
Y |
|
|
FndDiagTest1 |
Y |
To set up the Seed Data environment:
Follow these steps in JDeveloper before starting the Seed Data Framework tasks:
Start JDeveloper using the Oracle Fusion Applications Developer profile.
Seed Data user interface tasks are run from within a JDeveloper Business Components project.
Create the ADF Business Components artifacts to represent the logical data model, including entity objects and view objects in the project. Create the relationships between the entity objects and view objects in accordance with the Applications Standards. Add the objects to an application module that will serve as the entry point for the Business Service Object. The application module also serves as the container for the Seed Data Framework Configuration meta-data.
Run the Seed Data Configuration wizard.
The wizard is the graphical user interface tool used to configure Application Modules for Seed Data.
To launch the Seed Data Configuration Wizard, right-click the application module name in the Application Navigator tree view, and select Seed Data > Configuration > Edit as shown in Figure 56-1.
Note:
If the seed application module in use is derived from a subclass of OAApplicationModuleImpl, that sub-class and its dependencies, if any, should be made available in compiled form using the Libraries/Classpath feature of JDeveloper. If this step is not done, extract and upload will fail.
The Seed Data Configuration wizard launches and displays the Driver Definition Panel.
This panel, shown in Figure 56-2, initially shows the available view objects in the root level of the application module data model that can serve as Driver view objects.
Select the Driver check box for those view objects to serve as the Driver for Seed Data Extract. More than one Driver can exist within an application module; however, only one Driver can be specified at Extract time.
Select the Configure radio button for the Driver view object to configure it during this session. Only one driver view object can be configured during a single editing session.
Click Container Panel.
The Container Panel, as shown in Figure 56-3, shows the contained and reference relationships of the Driver view object. Also shown are the underlying table names that will be extracted from and updated to during the Extract and Upload processes.
View object relationships: The tree displays the model of the Seed Data Configuration. Relationships between the view objects are displayed. The relationship is either contained or just a reference. View links between the view objects that are based on Associations marked explicitly as Composition Association are shown as contained. Seed Data operations will be performed for all the view objects that are identified as contained.
Foreign key relationships are called reference relationships. They are identified by the existence of a view link between view objects backed by non-composite entity associations, or no entity associations at all, or a join between two entity objects (the referred entity object is marked as Reference in the View Definition) and a List of Values on the name field.
Tables Information: The list shows the tables that are updated during Seed Data upload. A non-editable list of tables is generated based on the declared data model indicated by a Source column value of Model. The Type column indicates whether the table is just Referenced or Updated. These tables and the explicitly added tables with Type Updated will be frozen for (near) Zero-Downtime patching.
Table Freeze involves making the table in the Production edition read-only and creating a replacement table in the Patch edition. The list of seed tables that will be inserted, updated or referenced during seed data upload is provided as metadata to the patching utility. This is auto-generated by the Configuration wizard by inspecting the underlying entity objects and base tables for a given driver view object.
If the entity objects of the configuration are not ADF Business Components-based, or custom insert or updates exist (such as through PL/SQL code), the seed data framework will not be able to accurately determine the set of tables participating in the seed data upload. In such cases, the seed data framework will not be able to accurately determine the set of tables to be frozen. The owner of the seed application module must declare the additional tables in the container panel. Failure to review and declare tables (such as by specifying a list that is incorrect or incomplete) that are participating in seed data upload is likely to cause data invalidation or corruption, as some tables will not be frozen and the Production Instance will directly be aware of seed data upload changes that should be limited to Patch Instance. Patch rollback also could leave orphan records in these cases.
Use the Add and Remove buttons to add or remove additional tables that are affected from the list. The list of updated tables is for information only. This information is used during patch application.
Table Name: This column shows the name of the table that is affected during seed data upload.
View Name: This column shows the name of the ADF Business Components view object where this table is declared. This column can also contain the name of the Java class or PL/SQL procedure which would be used for seed data upload.
Source: Shows the source of this definition. The value of M is reserved to indicate that the Table Name is derived from the ADF Business Components Model. You can create your own definitions for additional table entries.
Type: This column shows the update type of the definition. A value of Updated indicates that the definition table will be Updated at Seed Data Upload time. A value of Referenced indicates that this is a Referenced table only, and will not be updated by Seed Data Upload.
Click the Surrogate Panel.
Use the Surrogate Panel, shown in Figure 56-4, to declare surrogate attributes of the view objects of the Seed Data Configuration.
The tree displays the model of the Seed Data Configuration. View objects can be selected in the tree to declare a surrogate attribute of the selected view object.
Note:
If you have an entity object with a Surrogate ID that is involved in a parent-child relationship, but you are not able to view or select that Surrogate ID on the Surrogate panel, check the data model and confirm that you have checked the composition check box for that association. See the "Creating and Configuring Associations" section of the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework
Surrogate Attribute – Available: The left panel lists the attributes of the selected view object that can possibly be a surrogate attribute. The list will include primary key (PK) attributes that are of data type numeric.
Surrogate Attribute: The list on the right contains the attribute of the view object that has been identified as a Surrogate Attribute.
Alternate Key: Select the Alternate Key that will be used as the unique row identifier for the selected view object. The Alternate Key choice is based on the Alternate Keys available on the entity object of the selected view object. If the Primary Key has many attributes and one of them is being marked as a surrogate, all the other attributes in the Primary Key, except the one being marked as surrogate, must be included in the alternate key for that alternate key to be displayed in the list.
For Date Effective models, the above rule has been relaxed so that Effective Start Date, Effective End Date, Date Effective Sequence and Date Effective Flag are not required to be in the alternate key, even if they happen to be in the Primary Key to appear in the list.
To declare an attribute as a Surrogate Attribute:
Select the view object that contains the surrogate attribute. The left bottom panel will show the list of attributes that are potential surrogate attributes.
Select the Surrogate Attribute and click the shuttle button.
Click Reference Panel.
Use the Reference Panel, shown in Figure 56-5, to declare the Data Upload Mode for the Seed Data Configuration. Provide reference information on reference view objects.
The tree displays the model of the Seed Data Configuration. Reference view objects can be selected in the tree to declare information about the Seed Data Configuration of the referred view object. All the external references must be specified for the patch to succeed.
In the tree view, select the reference view object. The bottom left panel will contain a list of available application modules.
Select the application module that contains the Seed Data Configuration information for the reference view object.
Add a reference in the current application module to this application module by clicking the shuttle button.
Note:
If there are any Service Foreign Key LOVs defined in your model, review the different scenarios in Table 56-2, "Service Foreign Key LOV Scenarios" and verify that the steps listed for the scenario corresponding to your FK LOV are followed. Failure to follow the instructions in the document can cause problems during Seed Data Extract and Upload processes.
Table 56-2 Service Foreign Key LOV Scenarios
| Scenario | What must be done |
|---|---|
|
#1: Single attribute Foreign Key and single attribute Alternate Key (Example: PersonVO has Deptno and Dname. Deptno is the foreign key ID, and Dname is the foreign alternate key.) |
An LOV should be defined on the alternate key attribute, with the foreign key ID as a derived attribute.
|
|
#2: Single attribute Foreign Key and multiple attribute Alternate Key (Example: PersonVO has OrganizationId as foreign key ID, and OrganizationName+BusinessGroupName as the composite alternate key.) |
Each alternate key attribute needs to have an LOV defined, and each LOV should have all the alternate key attributes as the driving attribute, and the foreign key ID as the derived attribute.
|
|
#3: Single attribute Foreign Key and multiple attribute Alternate Key and one of the alternate key attributes is another foreign key. (Example: PersonVO has BirthOfCountry as foreign key ID, and BirthOfCity as another foreign key ID. BirthOfCity has BirthOfCountry+CityName as a composite alternate key.) |
The first foreign key (BirthOfCountry) must be resolved first, either based on Scenario #1 or #2. Then the second alternate key should filter by the first alternate key.
|
|
#4: Composite foreign key |
Each foreign key ID will be dealt with individually. For example, the foreign key id is OrgId+SourceId, then orgId and SourceId should be resolved based on solution in #1 or #2 or #3 separately. Then a validator must be defined to make sure combination of OrgId and SourceId is valid. This has the assumption that each individual attribute are a primary key itself. |
Note:
A UI-only LOV can be defined without a derived attribute. The Seed Data Framework normally would ignore such an LOV and no external reference metadata would be generated for it.
In some cases, it might be desirable to let the Seed Data Framework treat such an LOV as a regular LOV with derived attributes. To do this, you need a "fake" derived attribute defined on the LOV.
For example:
LinesStatusEO(LineStatusId, StatusCode) StatusEO(StatusCode)
Create a join between LineStatusEO and StatusEO in LineStatusVO.
Mark StatusEO as Reference.
Include the StatusCode attribute from StatusEO into LineStatusVO.
Note: The attribute would be named StatusCode1, since StatusCode from LineStatusEO is already a part of LineStatusVO.
Define the LOV on StatusCode with the derived attribute as StatusCode1.
Use the Seed Data Extract Manager tool to extract seed data from the pre-configured application modules. The generated extract files are partitioned by the module owner. Data can be filtered during extract time to limit the number of data files generated.
Note:
If you change the name of a seed data file after Extract, you also must manually update any references to that file name. Otherwise, proper ordering for Upload during patching run time for the files will not work as expected. So long as the physical file names and the names in task references match, the patching utilities will sequence the seed data tasks correctly.
The Seed Data Extract is driven off the Driver view object, as defined in the application module Configuration. This Driver view object serves as the root of the extract, and any contained child objects are extracted as containing data. Only one Driver view object is active during the Extract process.
There are two methods of starting a Seed Data Extract process:
From JDeveloper using the Seed Data Framework Console
By using an external Command Line Interface, as shown in Section 56.2.4.2, "Using the Extract Seed Data Command Line Interface"
To launch the Seed Data Framework Console from JDeveloper:
The Seed Data Console is the graphical user interface (GUI) tool used to run both Extract and Upload Seed Data tasks. The Console also can be used to view the underlying table data for the view objects of the application module data model.
Right-click the application module name in the Application Navigator tree view and select Seed Data > Extract to launch the Seed Data Framework Console, as shown in Figure 56-6.
If there are multiple database connections in the workspace, the Seed Data Console – Select Database dialog, shown in Figure 56-7, displays.
Although this is not the normal case, if you need to debug data on two different databases, this lets you choose which one to use.
Select from the list of database connections available to the project. The default selected database is the default connection set on the Project Properties, under Business Components.
Click OK to launch the Seed Data Console with the selected connection information.
The Seed Data Console main page, as shown in Figure 56-8, displays.
The tree view shows the selected application module name as the root node, and each of the configured Driver view objects as child nodes under the root. Only Driver view objects as configured by the Seed Data Configuration wizard will show in this view.
The right side of Console is the output area, where processing messages of Seed Data tasks are displayed.
Note:
The Seed Data Console does not specify the last applied version of the seed data file. Consequently, users always will see a warning message indicating incremental uploads have been turned off. This is harmless and can be ignored.
In the log, the warning will appear similar to:
[WARNING] 14:38:58 : -cfver parameter not passed, incremental uploads turned off
To start a Seed Data Extract operation, right-click the Driver view object from which you want to extract and select Extract Seed Data from the context menu, as shown in Figure 56-9.
The Select Extract Path dialog, shown in Figure 56-10, displays.
Type a directory path location in the File Name text box, or browse to an existing location using the directory browser. The directory location need not necessarily exist when typing a new name, as the directory paths will be created as needed during the Extract process. The Extract directory path selected is used as the Seed Data Extract Root for the generated extract files.
Seed Data Extract uses selection dialogs for Taxonomy partitions.
Functional Design
When starting the Extract process, if a Taxonomy Partition Attribute is found in the Driver view object, Extract will show the Taxonomy Partition selection dialogs. See "Determining the Taxonomy Partitioning Attribute" for steps taken by Extract to find the Taxonomy partition attribute, if any.
Taxonomy Products Dialog
The Select Application Taxonomy Product Modules, as shown in Figure 56-11, will display a fixed list of all the Taxonomy products enabled for use with the Seed Data Framework. If the list of products for which seed data extract needs to happen is known beforehand, users can pick them from the list of available products. Optionally, click Filter to filter the list of products to show only those products and Logical Business Area (LBA) modules for which records exist in the selected view object. Occasionally, when there are a large number of records involved, the it might take a while to filter the list of products.
If any Products or LBAs are selected that are not actually available in the view object, no attempt is made to extract for that partition. This is done by applying implicit Partition criteria, binding for each selected partition, and verifying at least one row exists for the Partition row set before attempting to extract.
For internal development test cases and debugging for Extract, you will need to know which partitions are available. To do so, you have to select the ModuleIds from the driver and discover which Product that ModuleId equates to from the Taxonomy table. If the driver view object moduleId is an LBA, you also will need to know under which Product that LBA falls; this involves selecting from the Taxonomy hierarchy table.
An alternate method is to just select all the Products and all the LBAs when prompted by the dialog. Then extract files are created for only those modules that actually exist. This will be a little slower, since building the complete LBA list from all Products can take a few seconds or longer. Then each selected partition is bound to determine the availability. This will not be the typical Applications use case, as developers will know which Products to select. It is necessary in a development case in which the Products are not known.
LBA Taxonomy Partitions
After selecting the Products, the second dialog, Select Application Taxonomy LBA Modules, may or may not be shown. If the selected Products were parents of explicitly available seed-enabled LBA modules, all the available LBAs for the selected Products are shown. Again, only LBA module types found in the driver view object rows, and set as Seed Enabled in the Taxonomy Service, are shown in the list.
If the selected Products were not parents, or there are no LBAs available, no LBA selection dialog is shown, and Extract is started for all the selected Products.
For the LBA selection dialog, the full LBA taxonomy path is shown, showing any parents of subLBAs, and the parent Product short name. Again, the user selects the desired LBA values by shuttling values to Selected.
Figure 56-12 shows the Select LBA Taxonomy Partitions dialog showing all the available LBAs found for the previously selected Receivables (AR), Payments (IBY), and Human Resources (PER) Products.
Extract Processing
After selecting LBAs, Extract proceeds to extract selected LBAs and selected base (non-parent) Product types, if any. Each Product and LBA type name value corresponds to a unique Extract file. Each Extract file will contain all rows containing the Taxonomy Partition Attribute (ModuleId or ApplicationId) value corresponding to each selected type.
Extract files are placed in folders according to the taxonomy path, starting at the Product short name, and including any LBAs and subLBAs as subdirectories. All the Extract file names follow the same pattern: <driver view object name>SD.xml.
Figure 56-13 shows a sample output selecting the three Receivable (AR) LBAs, creditCardErrors, customerProfileClasses, and miscellaneousReceipts, and General Ledger (AR) and Opportunity Management (MOO) Applications. The applications, AR and MOO, were explicitly defined in the entity, and contained no child LBAs.
Determining the Taxonomy Partitioning Attribute
The Taxonomy Partition Attribute on the Seed Driver view object is determined in the following manner, in order of precedence:
Attribute serving as ViewLink to ApplTaxonomySeedDataPVO ModuleId or AlternativeId attributes, or ApplicationPVO ApplicationId attribute.
Attribute serving as LOV to ApplTaxomomySeedDataPVO UserModuleName or AlternativeName attributes.
Hard-coded ModuleId attribute
Hard-coded ApplicationId attribute
Single File Implicit Partitioning
If no driver view object attributes pass above, single file implicit partitioning will be used and all rows will be extracted to a single extract file. In this case, no taxonomy partitioning dialogs will be shown.
The taxonomy owner for the corresponding file path is determined from the ApplicationModule package name.
For example, extracting from oracle.apps.fnd.lookups.service.FndLookupsAM will create the extract file in the FND folder under the user-specified extract root path.
Extract Manager Support for Seed Data File Dependencies
The Extract function adds metadata of the file on which the current file is dependent.
For example, the metadata shown in Figure 56-13 would be added using adxml comments for the case where the current file is dependent on it.
Example 56-1 Sample Metadata Using ADXML Comments
<!-- <run_after_tasks> --> <!-- adxml: <task_reference te="CZ" subdir="CZ" file_basename="ReferredSD.xml" identifier="UPLOAD"/> --> <!-- adxml: </run_after_tasks> -->
adxml are the comments added to the extract file at the beginning of the file. They are the same as normal xml comments except they have adxml: prepended to the commented text.
Extract gathers this information by using the Reference view object from Reference application module. Reference application module is configured by the user in the Reference panel of Seed Data Configuration. See Figure 56-5.
This information is used by the Patching Utility to create the order in which the files need to be uploaded so that the Reference data is available before the Referring data is loaded.
Static File Dependencies
For the cases where dynamically finding the file dependencies is not possible, or dynamic dependencies are not complete, you can set static file dependencies using an application module custom property for a view object instance, as shown in Table 56-3.
All files extracted from that view object would have the dependencies stamped in adxml comments.
Table 56-3 Application Module Custom Property for a View Object Instance
| Application Module Custom Property Name | Value | Example |
|---|---|---|
|
|
<product>:<path>:<filename>, <product>:<path>:<filename>,.. The static dependent file location consists of three parts separated by colons:
Multiple static external references should be separated by a comma. |
Property: SD_DEPENDENT_FILES_TimeDefinition1 Value: HCM:HCM/Per:LookupsSD.xml,FND:FND:ValueSetSD.xml |
Turning Off Dynamic File Dependency Generation
You can turn off the dynamic file dependency generation by defining the custom property shown in Table 56-4 on the application module.
Table 56-4 Property to Turn Off Dynamic File Dependency
| Application Module Custom Property Name | Value | Example |
|---|---|---|
|
|
true |
Property: SD_NO_DYNAMIC_EXT_REFS_FndObjects Value: true |
Output Log Level
The Log Level for the Seed Data tasks is used to increase or decrease the amount and type of log messages generated during processing. The default Log Level is set to INFO. This will display generated severe errors, warnings, and informational processing messages. To limit the number of log messages generated, set the log level higher, to Severe or Warning. To see more processing messages generated for debugging purposes, set the Log Level to a lower level. Set the Log Level to FINEST to see the most processing messages generated. These messages will generally only be useful to developers.
The Seed Data Extract process also can be initiated externally from JDeveloper using the Command Line Interface (CLI). Seed Data Extract command line parameters can be passed using one of two methods:
Directly on the Java command line
By using a command property file that is singularly passed on the command line
Extract Seed Data Java Command Line Syntax
java -cp $jdev_install/jdeveloper/jdev/oaext/lib/oracle.apps.fnd.applseed-rt.jar:$jdev_install/oracle_common/modules/oracle.odl_11.1.1/ojdl.jar oracle.apps.fnd.applseed.rt.extract.Extract -dburl <database connect url string without username and password> -dbuser <database user> -AM <fully qualified path to seed configured AM> -VO <seed Driver view object instance name> -dburl <database connect URL string without username and password> -dbuser <database user> -AM <fully qualified path to seed configured AM> -VO <seed Driver view object instance name> [-ExtractRootPath <output path location>] [-PartitionKeyIds <Taxonomy ModuleId values> | -PartitionKeyNames <Taxonomy short name values>] [-PartitionKeyIds <partition key id values>] [-PartitionKeyNames <partition key names>] [-log <Used to give the log Level (SEVERE to FINEST)>] [-loglevel <Used to give the location of the log file>] [-entid <enterprise id>]
Command Property File
java -cp $jdev_install/jdeveloper/jdev/oaext/lib/oracle.apps.fnd.applseed-rt.jar:$jdev_install/oracle_common/modules/oracle.odl_11.1.1/ojdl.jar oracle.apps.fnd.applseed.rt.extract.Extract [command property file]
The command property file is an external file that contains the command line properties in standard Java Properties format for each of the required and optional Extract command line properties. The format can be name=value, or name:value.
Seed Data Extract Command Line Parameters
The available Seed Data Extract parameters are listed in Table 56-5.
Table 56-5 Available Seed Data Parameters
| Property | Value | Required? | Example |
|---|---|---|---|
|
|
database connection URL in JDBC format without username and password |
Yes |
jdbc:oracle:thin:@fully_qualified_server_name:1991:database_name |
|
|
database user to be used for extract |
Yes |
fusion |
|
|
Application module name, fully package qualified |
Yes |
oracle.apps.fnd.applcore.flex.dff.descriptiveFlexfieldService. applicationModule.DescriptiveFlexfieldServiceAM |
|
|
Driver ViewObject instance name |
Yes |
DescriptiveFlexfield |
|
|
Path to extract seed data files |
No |
/home/seed/data |
|
|
Comma delimited Taxonomy Id values to extract, either ModuleId or ApplicationId, depending on partition strategy. |
No |
Taxonomy Module Ids: 4F1F0DFC58F87DB4E04044981FC62F46, 47110F64AC8F08E2E040449823C60DB6 Application Ids: 250, 667, 10047 |
|
|
Comma delimited Taxonomy name values to extract, either Product codes, or LBA names, or combination thereof |
No |
FND, HCM, invoices, receivables, cashManagement |
|
|
The Log Level (SEVERE to FINEST). |
No |
-loglevel FINE |
|
|
The location of the log file. |
No |
-log /home/seed/ex.log |
|
|
Enterprise Id numeric value. |
No |
-entid 1 |
Note:
The database password would be prompted. To avoid prompting, pipe it on the command line. The password must be piped in when output is redirected. For example, to pipe a password from the $FUSION_PASS environment variable to the Extract command line:
java Extract cmdline... <<! $FUSION_PASS
PartitionKey<Ids|Names> Properties
The PartitionKey properties drive how the seed data extract derives the data file partitions, which is the number of files generated. Each partition key will equate to a single extracted seed file, with all the rows that are owned by that particular module being extracted to its seed file.
You can use either the PartitionKeyIds or the PartitionKeyNames property, or a combination of both, to supply to the extract each of the unique file partitions that will be created. If no PartitionKey properties are specified, the default behavior is to extract all file partitions found from the driver view object, and all rows extracted to each corresponding seed data file.
You should use one of the PartitionKey parameters to limit the amount of files generated. Otherwise, the expected partitions will need to be determined from executing the driver view object query and perform a complete table scan of all rows. For very large tables with many thousands of rows, this could be a potentially large performance hit, and, depending on the complexity of the view object query and its joins, could take several minutes to hours to determine.
Property File Comments
In the command property file, any lines beginning with a pound sign (#) will be considered comments, and not processed in any way by the Extract tool.
You also can comment out specific entries in the multi-value comma delimited properties. For example:
PartitionKeyNames = FND, HCM, #FCM, GL, AM
This will ignore the FCM value entry, but keep others intact. A sample PartitionKeyNames command line option is shown in Example 56-2.
Example 56-2 Sample Command Line
java -cp $jdev_install/jdeveloper/jdev/oaext/lib/oracle.apps.fnd.applseed-rt.jar:$jdev_install/oracle_common/modules/oracle.odl_11.1.1/ojdl.jar oracle.apps.fnd.applseed.rt.extract.Extract -dburl jdbc:oracle:thin:@fully_qualified_server_name:1991:database_name -dbuser fusion -AM oracle.apps.fnd.applcore.flex.dff.descriptiveFlexfieldService.applicationModule.DescriptiveFlexfieldServiceAM -VO DescriptiveFlexfield -ExtractRootPath /home/seed/data -PartitionKeyNames HCM, invoices, cashManagement -loglevel FINER
Example 56-3 shows the contents of the sample Seed Extract Command Property File, located at /home/extract.properties:
Example 56-3 Sample Command Property File
#Sample extract property file, comment line AM = oracle.apps.fnd.applcore.flex.dff.descriptiveFlexfieldService.applicationModule.DescriptiveFlexfieldServiceAM dburl = jdbc:oracle:thin:fusion/fusion@fully_qualified_server_name:1991:database_name dbuser = fusion VO = DescriptiveFlexfield ExtractRootPath = /home/seed/data PartitionKeyNames = FND,HCM
Sample command line showing command line parameter to /home/extract.properties command property file.
java -cp $jdev_install/jdeveloper/jdev/oaext/lib/oracle.apps.fnd.applseed-rt.jar:$jdev_install/oracle_common/modules/oracle.odl_11.1.1/ojdl.jar oracle.apps.fnd.applseed.rt.extract.Extract /home/extract.properties
To launch the Seed Data Framework Console, refer to "To launch the Seed Data Framework Console from JDeveloper:" but select Seed Data > Upload.
When you right-click a Driver view object in the tree list, the menu shown in Figure 56-14 displays so you can select the Load Seed Data option.
In addition to the Load Seed Data option, discussed in Section 56.2.5.1, "Uploading Seed Data," three other options are available:
Set Log Level
Set how much information you want written to the log file. The least amount of information will be if this is set to Severe, and the largest amount of information will be is this is set to Finest. The default setting is Info, which will log Information, Warning and Severe messages.
Clean Mode
The default setting is Disabled. If Clean Mode is Enabled, it basically deletes all the existing records before proceeding to upload the given file. This option is exposed both through the command line interface for upload (-clean) and here.
Caution:
This option should be used extremely carefully as it might lead to irreversible data loss.
Customization Mode
The default setting is Do Not Preserve.
Seed Data Loader always sets the last_updated_by and created_by to zero when it inserts new records, and it always sets the last_updated_by to zero when it updates existing records.
Customers who have customized some of the Seed Data records are expected to set last_updated_by to a non-zero value.
By default when using the Seed Data Console, customizations are not preserved. They are overwritten.
However, on the command line, which is primarily intended for use at the customer site and for automated uploads, customizations are preserved by default. To override this, use the -nocust option.
To upload Seed Data, right-click the desired Driver view object from the Consoleview object tree list. Select Load Seed Data.
Important:
When you upload files, if the row already exists in the database and if it has been customized (last_updated_by <> 0), a "Skipped" message will be placed in the log and the row will not be updated. To correct this, change last_updated_by to 0 in both the database and the file before uploading.
The Select a file to load dialog, shown in Figure 56-15, displays.
Select either an XML file or its corresponding translation xliff file to initiate a National Language Support (NLS) upload.
Click OK to begin the Upload process on the selected file.
Upload Output
When the Seed Data upload finishes, the processing messages are shown in the output tabbed view window, in the tab corresponding to the view object against which the upload was run. See Figure 56-16.
You may see warning messages about columns being not updateable. Review these messages to determine if you can ignore them for your specific case.
The Seed Data Upload process can be initiated externally from JDeveloper using the Command Line Interface (CLI).
To run the command line version of the Seed Data Loader from within an ADE view, ensure the JDEV_HOME environment variable, shown in Table 56-6, is set to a valid JDeveloper installation directory. Include the jdeveloper sub folder if you are using JDeveloper integrated with WebLogic Server.
Table 56-6 Environment Variables for the Seed Data Upload CLI
| Variable name | Required? | Purpose |
|---|---|---|
|
|
No |
Should point to the full path to the JDeveloper installation. |
|
|
No |
Used to add additional classpath entries to the loader (in addition to the regular CLASSPATH setting which might not be modifiable in certain circumstances). This parameter is expected to include folders where Apps EAR archives are available in an exploded format (typically the product family level deploy folders). If the same ADF library is available from multiple locations, only one will be added to the classpath. |
|
|
No |
Used to add additional classpath entries to the loader (in addition to the regular CLASSPATH setting which might not be modifiable in certain circumstances). This parameter is expected to include folders where techstack libraries are made available. On a provisioned system, it should include at least these directories: fmw1/atgpf/atgpf/modules/oracle.applcore.model_11.1.1 fmw1/oracle_common/modules fmw1/atgpf/modules Note: The primary difference between APPLSEED_CLASSPATH and APPLSEED_TS_CLASSPATH is that the JAR files coming from APPLSEED_CLASSPATH are put through a unique filter that filters unique JAR files by file name. This is possible because ADF libraries follow a naming convention. However, there is no common naming convention across techstack libraries (there could be a util.jar from JDBC and another from the XML parser). Therefore, the JAR files coming from APPLSEED_TS_CLASSPATH are not filtered by filename. |
|
|
No |
Used to specify a file path, each line of which will be treated as a classpath entry similar to the entries in APPLSEED_CLASSPATH. |
|
|
No |
Used to specify a file path, each line of which will be treated as a classpath entry similar to the entries in APPLSEED_TS_CLASSPATH. |
Command Line Syntax
Example 56-4 shows a sample Seed Data upload command entered on the CLI, and Example 56-5 shows a sample command line command for a Key Flexfield application module.
Example 56-4 Sample Seed Data Upload Command on the CLI
java -cp $jdev_install/jdev/oaext/lib/key_ff_app_module_name.jar key_ff_app_module_name.loader.Loader -am <fully qualified application module name> -dburl <database url in jdbc format without username and password> -dbuser <database user> -file <complete path to the data file> [-config <bc4j config name>] // Example: KeyFlexfieldServiceAMLocal, KeyFlexfieldServiceAMShared, KeyFlexfieldServiceAMTest [-cfver <checkfile version>] // Obsolete. Do not use. [-atomic] // If used, the loader will load all the records or none of them (basically will stop after the first failure) [-nls] // Used to indicate to the loader that it should treat the given file as an xliff [-clean] // Cleans up any existing records before starting to upload from the file (use with caution) [-loglevel] // Used to give the log Level (SEVERE to FINEST) [-log] // Used to give the location of the log file [-commitsize] // This parameter is optional. The The default value of commitsize is 1; the maximum allowed value is 9999. The commitsize parameter is used to decide the frequency for committing the seed loader transaction. For the default case with commitsize at 1, the transaction is committed after every 1 records, or after all the records are processed, whichever comes first. Note that the commits are only at the top level entity (and not in middle of child records), so commit may not occur exactly every N records, but at the top level entity after N records (top level and child records together) have been processed. // Note: The previous name for the commitsize parameter was batchsize. However, this was getting confused with the JDBC batch value, and hence, it was decided to rename it to commitsize. [-entid <enterprise id>] // load data only for the given enterprise
Note:
The database password would be prompted. To avoid prompting, pipe it on the command line. The password must be piped in when output is redirected. For example, to pipe a password from the $FUSION_PASS environment variable to the Loader command line:
java Loader cmdline... <<! $FUSION_PASS
Three modes can be invoked when running a Seed Data Upload from the command line.
-clean: This flag's primary purpose is to make the set of records in the database reflect exactly what is delivered in the seed data file. If the set of records in the database becomes out of sync with what is delivered in the file, the -clean flag can be used to load the seed data file and make sure the database only has those records delivered from the file. This is turned off by default.
-atomic: This flag's primary purpose is to let the seed framework ensure that all the records in a given file are loaded. If all records are not loaded, none will be loaded. If even one record fails, the loading is stopped and all the previously loaded records are rolled back. That is, a single commit is issued towards the end of the file. This is turned off by default and a commit is done after every top level record.
-nocust: This flag's primary purpose is to let the seed framework know that it should not preserve any customizations done by the customer in the database version of the records. Data from the file is expected to overwrite anything that is in the database. This is turned off by default.
Important Points
The database password would be prompted. The password can be piped in to avoid prompting. The password must be piped in if output is redirected.
A failure during the cleanup stage does not prevent the subsequent loading of the records from the file.
The -clean, -nocust and -atomic flags can be used independently of each other.
What is deleted when -clean is used?
The clean mode deletes all the records that satisfy a particular condition. In normal use cases, this is the partitioning criteria (ModuleId or ApplicationId) used when the data was extracted. The Seed data file has metadata about the partitioning attribute (ModuleId, ApplicationId or any other partitioning scheme) and the exact values for those attributes used during extract.
Example
Using the Messages model from the Oracle Fusion Middleware Extensions for Applications, when PER/SomePerLba developers extract their messages, they will receive a set of Messages owned by that LBA. The seed data file captures this metadata that is used during -clean to determine the set of records to remove. In this case, all the messages owned by PER/SomePerLba will be removed.
The set of records deleted does not depend on the set of records in the file. It is only driven by the partitioning metadata stored inside the file. The loader would not have even read the records in the file by the time the cleanup is made.
Example
If PER/SomePerLba owns 10 messages in the database and an incoming MessageSD.xml brings in only six messages, which might be the same as or different from those in the database, the 10 messages in the database are all removed and the ones from the file are all loaded. If the loading succeeds, the database should have only six records owned by PER/SomePerLba - exactly what the seed data file brought in.
Customizations and -clean
The -clean mode currently does not preserve customizations. The seed framework identifies customized records by a non-zero last_updated_by. Such records are not updated by the seed framework and a warning is issued that the record has been customized in the database. The clean mode, however, does not currently honor this principle and deletes even the customized records.
When are deletes committed?
The cleanup and the subsequent loading run in a single transaction. Therefore, a failure during the loading will roll back the deletes. Because the seed framework - by default - commits after every top level record, the cleanup - by default - is committed or rolled back along with the very first top level record. If subsequent top level records fail, they all will be left out of the database. Therefore, only a subset of the records that came in the file will remain. This behavior changes when using the -atomic flag. This flag essentially says "make sure all the records, or none of the records, in the file are loaded." In this case, the cleanup and the loading are committed only once towards the end of the file. Even if one record fails, the deletes and any intervening loads are rolled back.
In some cases, Application Modules developed and owned by one team might have to be shared by some other team. In such cases, the team that developed the application module owns the module and the data-model associated with it, but the team that is consuming it owns the seed data and the relevant extract files.
In Figure 56-17, the team that is developing the application module packages the module into an ADF Business Components library.
The consuming team includes these libraries in the project using the Libraries/Classpath feature of JDeveloper. Once imported, developers can use these libraries to extract and upload seed data, but cannot edit the Seed Data configuration.
The imported Business Components can be seen using the Business Components Import feature of JDeveloper. Once imported, developers can use these libraries to extract and upload seed data, but cannot edit the Seed Data configuration.
Since Application Modules shared using an ADF Business Components library are not shown by JDeveloper in the Application Navigator, users must right-click the Business Components project into which they imported the shared libraries. The Seed Data menus would also be available on any Business Components project node in the Applications Navigator tree of JDeveloper.
Clicking any of the Seed Framework menu items will display a tree structure showing all the Seed Framework-enabled Application Modules (those that have at least one Seed Data driver view object configured within them) available to that project.
Users can choose an available application module and click OK to display the familiar Seed Data console to perform and extract or upload activities.
The Seed Data Loader supports incremental updates and Java Database Connectivity-based National Language Support updates. These are summarized in Table 56-7.
Table 56-7 Summary of Seed Data Update Features
| Feature | Applicable to | Default Setting | Design time Control | Runtime Control |
|---|---|---|---|---|
|
Incremental Updates |
Only US language seed data files |
On |
Disabled by setting SD_INCR_MIDTIER_<ViewDefinitionName> to false. |
Disabled by using optional command line parameter -noincr Disabled by setting APPLSEED_NO_INCREMENTAL to true |
|
JDBC Mode |
Only translation seed data files |
On for newly extracted files |
Disabled by setting SD_NLS_USE_ADF_<ViewDefinitionName> to true |
Disabled by setting APPLSEED_NLS_USE_ADF to true |
The Seed Data Loader always updates all the records from the seed data file, even if those records are already present in the target database. The Seed Data Loader only updates the records from the seed data file that have changed in the target database. For certain kinds of requirements where it is desirable to have the seed data loaded as a set, and therefore incremental updates are not desirable, the Seed Data Framework provides an optional feature that allows product teams to disable this feature.
During extract, the Seed Data Framework computes MD5 checksums on the source record by taking all the fields that make up the record (excluding key attributes, history columns and non persistent fields). This checksum is embedded in the seed data file as additional record level metadata. At load time, if the record is found existing in the target database, the same algorithm is used to compute the checksum on the target record. By comparing the two checksum values, the seed data loader identifies if the record has undergone a change and needs an update. Updates are triggered only for those records for which the checksums do not match.
This incremental update feature is applicable to only US language seed data XML files and is enabled by default. For translated seed data, there is no provision to do incremental updates.
To disable this feature for a particular seed data driver view object and all its child view objects, the SD_INCR_MIDTIER_<ViewDefinitionName> property should be added to the application module.
Set the value of this property to false to turn off incremental updates.
SD_INCR_MIDTIER_ValueSetVO false
Note that the incremental updates feature requires new metadata, in the form of checksums, to be embedded into the seed data file. Consequently, only newer seed data files can take advantage of this feature. Note that the incremental updates feature requires new metadata in the form of checksums to be embedded into the seed data file. Consequently, only newer seed data files can take advantage of this feature. With older seed data files, the seed data loader shall continue to update all the records, even if the application module has the feature enabled using the SD_INCR_MIDTIER property
As a debugging aid, the seed data loader also allows for incremental updates to be conditionally turned off at run time. Use the -noincr optional command line parameter to the loader or set the APPLSEED_NO_INCREMENTAL environment variable to true.
The Seed Data Loader loads seed data using the ADF components developed by product teams. Consequently, all the business rules, validation logic, and custom code built into Oracle Fusion Applications ADF components also are invoked. Translation seed data delivery usually involves only simple updates to existing records. Using plain JDBC calls, instead of ADF, to update existing records allows for much faster loads of translated seed data.
Newer translation seed data files have additional metadata that signal the loader to use the JDBC mode wherever possible. This additional metadata includes SQL fragments that the loader uses at load time to trigger JDBC updates, instead of the well-known ADF-based loads. This JDBC mode is designed to achieve functional parity with the existing ADF mode, and is the preferred way to deliver translation seed data.
It is enabled by default for newly-created translation seed data files, except date effective translation seed data, which rely on additional logic built into the ADF. It should be noted that US language (XML) seed data files continue to be loaded through ADF. The JDBC mode is tailored only for translation (XLF) seed data files. If certain kinds of translated seed data need to be always loaded using ADF, it is possible to do so using one of these ways:
Design time - Define a custom property SD_NLS_USE_ADF_<ViewDefinitionName> and set its value to true.
Runtime - Define an environment variable APPLSEED_NLS_USE_ADF and set its value to true.
The Seed Data Framework will handle localized data stored in translation tables in a consistent manner. Translatable attribute data will be extracted separately for only the US base language into Ora-XLIFF compliant format files.
Translation teams will translate the base US language XLIFF into the various language translation files, one file for each supported language. The files are to be stored in a separate language folder, named for its language code.
At upload time, Seed Data Loader will recognize an incoming translation language XLIFF file automatically, and perform the necessary updates to the language tables.
Ora-XLIFF format files are automatically generated for those data models which have translatable data. Only the US language data is extracted. The XLIFF file is created in a language sub-folder, named US, and the file name is named the same as the base seed data XML file, with an extension of .xlf.
The seed data base and XLIFF files must be treated as a single entity. Any changes to either base or translated attributes that would require a re-extract, would necessitate that both the re-extracted base XML and US XLIFF files be delivered as units. There is metadata in the files to ensure that the base and XLIFF files match and were extracted together.
Translation teams will create the translation XLIFF files starting from the initial US file. Each supported language will have its own XLIFF file. The files will be stored in a separate language sub-folder, named for the language code. The files will be named the same as the base XML name, with the .xlf extension.
At upload time, the Seed Data Loader will recognize an incoming translation language XLIFF file automatically, and perform the necessary updates to the language tables, based on the target language value from the XLIFF file.
Each translated language XLIFF file is loaded individually as a separate entity.
Base XML Must Be Loaded First
The base seed data XML file must be successfully loaded before loading any language translation XLIFF files. No new inserts of language rows are performed, only updates to existing rows.
When loading the base seed XML file, the language rows are initially created using the US translation values. Then when loading the language translation files, the rows are updated using the incoming language values. This way, it is not necessary to have translations for every single row. If no translations exist, the fall back is then to use the US language row.
It is not necessary to upload the US language XLIFF file, as US translation data is already saved in the base seed data XML file.
For the Seed Data Framework to work with translated data and perform the necessary read and updates to the language translation tables, the application data model must conform to the Oracle Applications Multi-language support guidelines.
See Section 9.2, "Using Multi-Language Support Features" for more information on creating translatable data models.
|
 Copyright © 2011, 2013, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|
