3 Using Oracle JDeveloper for Customizations

Oracle Fusion applications are built using Oracle Application Development Framework (Oracle ADF) artifacts on Oracle Fusion Middleware, including the following:

• Application modules: An application module is the transactional component that UI clients use to work with application data. It defines an updatable data model along with top-level procedures and functions (called service methods) related to a logical unit of work related to an end-user task.

• Entity objects: An entity object represents a row in a database table and simplifies modifying its data by handling all data manipulation language (DML) operations for you. It can encapsulate business logic to ensure that your business rules are consistently enforced. You associate an entity object with other entity objects to reflect relationships in the underlying database schema to create a layer of business domain objects to reuse in multiple applications.

• View objects: A view object represents a SQL query and simplifies working with its results. You use the SQL language to join, filter, sort, and aggregate data into whatever form is required by the end-user task being represented in the user interface. This includes the ability to link a view object with other view objects to create master-detail hierarchies of any complexity. When end users modify data in the user interface, your view objects collaborate with entity objects to consistently validate and save the changes.

• Task flows: A task flow defines the flow of control throughout an application. It can also be included in a page as a region, where users can navigate through a series of page fragments, without leaving the original page.

• JSPX pages and page fragments: The view layer of Oracle Fusion Applications consists of a small number of pages per application. These pages then contain task flows, which in turn contain several page fragments.

When you customize Oracle ADF artifacts, you usually work in an overview editor that allows you to make your customizations declaratively. For example, the following figure shows the editor for an entity object. Among other things, you can set validation or change how the UI displays the data.

Figure 3-1 Overview Editor for Entity Object

For JSP pages, you work in a WYSIWYG environment using the Design tab in the editor window, as shown in the following figure.

Figure 3-2 Design Editor for JSP Pages

Oracle Fusion applications are built using SOA composite artifacts on Oracle Fusion Middleware, which include the following:

• Service components: A service component implements the business logic or processing rules of a SOA composite application. Available service components include the following:

  • Business Process Execution Language (BPEL) processes: A BPEL process enables you to integrate a series of business activities and services into an end-to-end business process flow.

  • Business rules: A business rule enables you to create business decisions in your business process flow based on rules.

  • Human tasks: A human task enables you to create human workflows that describe the tasks for users or groups to act upon as part of an end-to-end business process flow. You use Oracle Business Process Management Worklist (Oracle BPM Worklist) to act upon the tasks during runtime.

  • Oracle Mediator: An Oracle Mediator enables you to define services that perform message and event routing, filtering, and transformations within the SOA composite application.

• Binding components: A binding component establishes the connection between a SOA composite application and the external world. There are two types of binding components:

  • Services provide the outside world with an entry point to the SOA composite application. The Web Services Description Language (WSDL) file of the service advertises its capabilities to external applications. These capabilities are used for contacting the SOA composite application components. The binding connectivity of the service describes the protocols that can communicate with the service (for example, Simple Object Access Protocol (SOAP)/Hypertext Transfer Protocol (HTTP) or Java EE connector architecture (JCA) adapter).

  • References enable messages to be sent from the SOA composite application to external services in the outside world.

• Wires: A wire connects services, service components, and references into a complete SOA composite application.

1. Start JDeveloper using the Oracle Fusion Applications Developer role, as shown in the following figure.

   Figure 3-3 Oracle Fusion Applications Developer Role

   
2. In JDeveloper, from the main menu, choose File > New to open the New Gallery. In the New Gallery, select Applications > Fusion Applications Customization Application.
3. In the Step 1 page of the FA Customization Application dialog, enter the following and click Next:

   • Application Name and Directory: These are the name and location of your customization application, and can be anything you like.

   • Fusion Database: Enter the connection to your Oracle Fusion database.

   • Application Package Prefix: This can be anything, but must not start with oracle.

   • Deployed Application Ear: Browse to the exploded EAR for the application you want to customize.

   • Policy Store Security Information: Browse to the exported jazn-data.xml file. First, you must export all predefined function security policies of the application that you are customizing into a jazn-data.xml file. For details about how to export the application policy store, see the "Securing Oracle Fusion Applications" chapter in the Administrator's Guide. For information about security customization, see Customizing Security for Application Artifacts .

4. Complete the wizard by changing any default settings as needed.

After you complete the wizard, an application with a project is created for you. This application is configured to be the same as a deployed Oracle Fusion application. For example, it is connected to the same database, same metadata repository, and has similar web.xml and weblogic.xml settings. This configuration allows it to work correctly when deployed into your Oracle Fusion Applications environment, and also ensures that when you test your customizations locally in JDeveloper Integrated WebLogic Server, the customizations behave as they will in the full test environment.

JDeveloper also creates a connection to the exploded EAR directory named Customizable Archive, which is accessible from the Application Resources panel of the Application Navigator. The following figure shows a connection to the exploded EAR directory for an application.

Figure 3-4 Application Resources Connection to Exploded EAR Contents

[[this section is no longer needed, but until the IDE is done, will keep, just in case]]

Configure the customization application workspace by copying the configuration files from the exploded JAR file to the newly created application workspace. This ensures that your new workspace is configured the same as the application you are customizing.

1. Copy the following from the exploded EAR file's /adf/META-INF directory to the /.adf/META-INF directory of the new workspace:

   • adf-config.xml

   • connections.xml

   For example:

   cp <ExploadedEarLoc>/adf/META-INF/adf-config.xml <NewJwsDir>/.adf/META-INF
   

2. Copy the weblogic-application.xml file from the exploded EAR file's /adf/META-INF/ directory to the /src/META-INF/ directory of the new workspace.

3. Copy the following from the exploded EAR files /WEB-INF directory to the new UI project's /public_html/WEB-INF directory:

   • web.xml

   • trinidad-config.xml

   • portlet.xml

   • weblogic.xml

   • oracle-portlet.xml

4. In JDeveloper, open the newly copied adf-config.xml file and change the metadata store to use the FileMetadataStore class, as shown in Example 3-1. This setting will allow you to test your customizations using the integrated WebLogic server (WLS).

5. If the application you are customizing launches Enterprise Scheduler (ESS) jobs, you will need to remove those references from your application if you plan on testing your customizations in integrated WLS. If you will only be testing in a deployed environment, you can proceed to the next step.

   To remove the references:

   1. In the UI project, open the newly copied-over web.xml file.

   2. Search for the following entries and delete them:

      <ejb-local-ref>
        <ejb-ref-name>ess/metadata</ejb-ref-name>
        <ejb-ref-type>Session</ejb-ref-type>
          <local>oracle.as.scheduler.MetadataServiceLocal</local>
          <ejb-link>MetadataServiceBean</ejb-link>
         </ejb-local-ref>
         <ejb-local-ref>
           <ejb-ref-name>ess/runtime</ejb-ref-name>
           <ejb-ref-type>Session</ejb-ref-type>
           <local>oracle.as.scheduler.RuntimeServiceLocal</local>
           <ejb-link>RuntimeServiceBean</ejb-link>
         </ejb-local-ref>
      

6. If you're are customizing ADF Task Flows that are used for SOA human tasks, extract the hwtaskflow.xml file from the UI jar that you are customizing and, once extracted, copy that file into the adfmsrc directory in you UI project.

   If you are customizing more than one ADF Task Flow for a human task, and they reside in different UI jars, you will need to either create separate projects for each UI jar which contains an ADF Task Flow for Human Task which you plan to customize, or merge the hwtaskflow.xml from each UI jar, as shown in Example 3-2.

<adf-config xmlns="http://xmlns.oracle.com/adf/config">
  ......
  <mdsC:adf-mds-config version="11.1.1.000">
    <mds-config xmlns="http://xmlns.oracle.com/mds/config">
        <metadata-store-usages>
          <metadata-store-usage id="WebCenterFileMetadataStore" 
                                default-cust-store="true">
            <metadata-store class-name=
                   "oracle.mds.persistence.stores.file.FileMetadataStore">
              <property name="metadata-path" value="."/>
            </metadata-store>
          </metadata-store-usage>
        </metadata-store-usages>
      </persistence-config>
    </mds-config>
</adf-config>

<?xml version = '1.0' encoding = 'UTF-8'?>
<hwTaskFlows xmlns="http://xmlns.oracle.com/bpel/workflow/hwTaskFlowProperties">
   <ApplicationName>worklist</ApplicationName>
  <LookupType>LOCAL</LookupType>
   <TaskFlowDeploy>false</TaskFlowDeploy>
   <SoaServer>
      <ejbProviderUrl/>
      <aliasKeyName/>
      <keyName/>
      <connectionName/>
   </SoaServer>
   <TaskFlowServer>
      <hostName/>
      <httpPort/>
      <httpsPort/>
   </TaskFlowServer>
   <hwTaskFlow>
      <WorkflowName>FinFunTransactionApproval</WorkflowName>
      <TaskDefinitionNamespace>
          http://xmlns.oracle.com/apps/financials/c
mponents/ledgerSoa/fun/intercompanyTransactions/approvalComposite
FinFunIntercoTransactionsApprovalComposite/FinFunTransactionApproal
      </TaskDefinitionNamespace>
      <TaskFlowId>FinFunTransactionApproval_TaskFlow</TaskFlowId>
      <TaskFlowFileName>
        WEB-
NF/oracle/apps/financials/commonModules/intercompanyTransactions/
i/approvalTask/flow/FinFunTransactionApprovalTaskFlow.xml
      </TaskFlowFileName>
   </hwTaskFlow>
   <hwTaskFlow>
      <WorkflowName>
        FinFunEnterDistRequestForAction
      </WorkflowName>
      <TaskDefinitionNamespace>
        http://xmlns.oracle.com/apps/financials/c
mponents/ledgerSoa/fun/intercompanyTransactions/approvalComposite
FinFunIntercoTransactionsApprovalComposite/FinFunEnterDistRequest
orAction
      </TaskDefinitionNamespace>
      
<TaskFlowId>
  FinFunEnterDistRequestForActionTaskFlow
</TaskFlowId>
<TaskFlowFileName>
  WEB-
NF/oracle/apps/financials/commonModules/intercompanyTransactions/
i/enterDistTask/flow/FinFunEnterDistRequestForActionTaskFlow.xml
</TaskFlowFileName>
</hwTaskFlow>
<hwTaskFlow>
  <WorkflowName>FinGlJournalApproval</WorkflowName>
  <TaskDefinitionNamespace>
    http://xmlns.oracle.com/apps/financials/c
mponents/ledgerSoa/gl/journals/journalEntries/approvalComposite/F
nGlJrnlEntriesApprovalComposite/FinGlJournalApproval
  </TaskDefinitionNamespace>
    <TaskFlowId>FinGlJournalApprovalTaskFlow</TaskFlowId>
      <TaskFlowFileName>
        WEB-
NF/oracle/apps/financials/generalLedger/journals/journalEntries/u
/journalApprovalTask/flow/FinGlJournalApprovalTaskFlow.xml
      </TaskFowFileName>
   </hwTaskFlow>
</hwTaskFlows>

Instead of importing the actual artifacts, you create an ADF Library from the JAR file that contains the artifact you want to customize. You then import that library into your project.

To create the library, add a dependency from the project to the JAR file to be customized. For example, if you want to customize a page, you would create a dependency from your view project to the JAR file that contains the page you want to customize.

1. In the Resource Palette, click the new icon and choose New > New Connection > File System.

2. Create a connection to the exploded EAR directory.

3. In the Application Navigator, select the project to which you want to import the artifact to be customized.

4. The Resource Palette shows all the JARs in the exploded ear directory as ADF libraries that can be imported into your application. In the Resource Palette, expand the library directory that contains the ADF Library for the JAR file you want to customize. Model libraries are in the /APP-INF/lib directory, and UI jars are in the /WEB-INF/lib directory.

5. Right-click the JAR file and choose Add to Project.

If you've just imported a library into a view project, you need to do some additional configurations.

1. Add the ApplCore tag library to the web project.

   1. Double click the view project to open the Properties dialog.

   2. Select JSP Tag Libraries.

   3. Add the Applications Core (ViewController) library.

2. Add servlets expected by the web.xml file from the ADF library to the project.

   1. In JDeveloper, from the view project, open the web.xml file.

   2. Search for servlets whose class name begins oracle.apps (ignore any that begin with oracle.apps.fnd.

   3. Go to the exploded war directory and grep for the class name(s) found in the web.xml file.

   4. Import the associated library to the project, as you did in Step 1.

Fusion applications often contain JAR files that contain extensions of base classes. You need to include these extensions in your application.

1. Import any customization classes in the EAR file.

   1. In the Resource Palette, in the APP-INF /lib directory of the EAR, search for libraries whose names begin with AdfExt.

      [[Reviewers: Ning thought that the jar names would begin with "Ext," but I only see AdfExt. Are these the correct jars?]]

   2. Copy those jar files to the <JDev_HOME>/jdev/extensions directory. For example:

      cp <ExploadedEarLoc>/APP-INF/lib/AdfExtCust.jar <JDev_HOME>/jdev/extensions
      

   3. In the Application Navigator, select the corresponding project.

      [[Reviewers: which project do these get imported into?]]

   4. In the Resource Palette, right-click the JAR file to be imported and choose Add to Project.

You should now be able to run the new projects with the imported artifacts. If you cannot, that generally means that you are missing dependencies.

1. In Application Navigator, click the Navigator Display Option icon, and choose Show Libraries. All libraries in your project will now display in the Application Navigator.

2. In the project to be tested, expand the ADF Library node.

3. For a model project:

   1. Find and expand the packages, until you find a service package, for example, competitorsService.

   2. In that service package, expand the applicationModule package.

   3. Right-click the application module (for example, CompetitorAM.xml) and choose Run with [[reviewers: should they run with PerfTrace or PUTF]] to run the application module.

4. For a view project:

   1. Expand the META-INF directory.

   2. Right-click the adfc-config.xml file and choose Run.

If you get any class not found errors, or no def found errors, then most likely a dependent JAR file is missing.

Use the search field in the Resource Palette to find the missing JAR, and then import that corresponding library into the project, as you did for the pre-seeded cusotmizations.(for more information, see Import Pre-Seeded Customizations).

Once all errors are fixed, you can begin to customize the artifacts.

1. In a runtime environment, access the page you want to customize and open it in the Source view of Page Composer. The page's structure is displayed, and from here, you can identify the page name, or if the customization is actually on a page fragment within a task flow, you can identify the task flow name. For more information about using Page Composer, see the "Customizing Pages" chapter in the .
2. If you need to customize a page fragment (.jsff) file within a task flow, from Page Composer, click Manage Customizations to open the page in the Manage Customizations dialog. From here, you can identify the .jsff file name.
3. In JDeveloper, after you have created a connection to the exploded EAR directory, you can use the Filter Customizable Archive dialog to search for the .jsff file or the task flow file.
4. Right-click the file and choose Customize to import the file and open it in JDeveloper.
5. Right-click the file, and choose Go to Page Definition.

   The page definition file shows you the view objects being used by the components on the page to return the data.

6. Open the view object in JDeveloper.

   The view object can be customized, or if needed, you can identify the associated entity object and customize that. Note that you can also identify the application module from here.

When working in teams of multiple developers implementing multiple customizations in an application, observe the following guidelines to avoid conflicts of customized metadata:

• Create small, focused customization application workspaces for the application, logically divided among functional areas.

• Ensure that any given artifact is customized in only one customization application workspace.

• Share the customization application workspaces among customization developers, ensuring that only one developer at a time implements customizations in the workspace.

• Make sure that all custom JAR files have different names that begin with the prefix Xx, for example XxMyJar.jar.

By following these guidelines, you can avoid situations where developers inadvertently overwrite each others customizations, and make sure that customizations don't interfere with product upgrades.

You can use JDeveloper to run applications in Integrated WebLogic Server. To accomplish this, you need to identify a runnable target that contains the customized object.

When identifying which artifact to customize, you typically start by opening the page that exposes that artifact, and then drill down to identify the specific object to customize. The top-level page you start at (typically a .jspx file) is the page you will run to test customizations, so it is important to take note of the name of that file when you begin customization. Page fragments (.jsff files) are not runnable objects.

You will also need to make sure that your local test environment has the necessary security configuration to run the application. For more information, see Customizing Security for Application Artifacts . In particular, you will need to consult a security administrator to export all predefined function security policies of the application that you are customizing into a jazn-data.xml file. For details about how the security administrator exports the application policy store, see the "Securing Oracle Fusion Applications" chapter in the Administrator's Guide.

For more information about running locally, see the "Running a Fusion Web Application in Integrated WebLogic Server" section in Developing Fusion Web Applications with Oracle Application Development Framework. For more information about identifying an artifact to customize see Determining Which Artifacts You Need to Customize.

There may be occasions when you need to import other customizations into your application workspace. For example, someone else may have made customizations to an application module to which you need to make changes as well. Before you make your customization, you must import that application module into your customization application workspace.

If you need to import customizations made to a single page or page fragment, you can use the Manage Customizations dialog to download the file, as described in the "Customizing Pages" chapter in the . Save the customization files to a zip or JAR file.

If you need to import multiple customizations available in the metadata repository for an application, you use the exportMetadata Oracle WebLogic Scripting Tool (WLST) command. For more information, see the "Application Metadata Management Commands" section of WLST Command Reference for WebLogic Server. This command saves the customization files in a JAR file that you can import into your application workspace. For procedures, see the "Viewing ADF Library Runtime Customizations from Exported JARs" section of the Developing Fusion Web Applications with Oracle Application Development Framework.

If you want to use extensions (for example, if you want to add a custom entity object to an existing application module), the extensions must be deployed into the environment to which you have a connection. For more information, see About Deploying Customizations and Extensions.

During the process of customization, it is possible that the base application that you are customizing is updated with a patch. If this happens, you might need to resynchronize the configuration files in your local customization application workspace from the exploded EAR of the application you are customizing.

When you create a customization application workspace in your local development environment, workspace configuration files (such as, adf-config.xml, connections.xml, and web.xml) are copied to the local development environment. In some cases, the file is modified to allow you to implement and test customizations locally. When a patch is applied to the base application, these configuration files might change, and would therefore need to be synchronized to your local development environment so that you can continue to implement and test customizations.

JDeveloper allows you to check for and process updates to the workspace configuration files after a patch has occurred on the base application. When you run the check, there are three potential results for each file:

• The file in the local development environment does not need to be updated.

• The file in the local development environment must be updated, and can be updated safely because the local version has not been modified.

• The file in the local development environment must be updated, but cannot be updated safely because the local version has been modified.

After the check, JDeveloper lets you decide how to handle the update. If you choose to proceed with the updates, backups of the local files are created. You can use the backup files to manually merge changes into the updated files if necessary.

1. Right-click the SOA composite application project you created in Configuring the SOA Application Workspace in and go to Project Properties > Libraries and Classpath.
2. Click Add Library, and select the BC4J Service Client library.

   Click OK to close the Add Library dialog.

3. Click OK to close the Project Properties dialog.

   By adding this library to your SOA project, you avoid the design time error you may have received in Step 88.d in Configuring the SOA Application Workspace in .

4. Click the Validate icon in the Design view of the composite.xml file. The error shown in Step 88.d that you may have received for the partner link should now be resolved.
5. Make the customization classes and values available in your project.

   There are two types of customization classes:

   • Applications Core customizing classes are available from the Applications Core shared library. See About Customization Layers for the list of Applications Core customization classes permitted in JDeveloper.

   • Product team customization classes are available in the appropriate EAR file. These customization classes are bundled in a JAR file in the EAR's APP-INF/lib directory. These JAR files follow a naming convention of Ext...jar. Therefore, you must get these JAR files from the deployed area, and perform the following steps:

     • Put the customization class JAR file under $JDEV_HOME/jdev/extensions.

     • Add the JAR file in the new project's library and class path setting.

6. Right-click the SOA composite application project and go to Project Properties, then Libraries and Classpath.
7. Add the Applications Core library to the SOA composite application project, as shown in the following figure.

   Figure 3-10 Applications Core Library

   
   Description of "Figure 3-10 Applications Core Library"
8. Go to Application Resources, then Descriptors, then ADF META-INF, and then adf-config.xml.
9. Add the appropriate customization class in the MDS Repository configuration, such as oracle.apps.fnd.applcore.customization.SiteCC.
10. Right-click the SOA composite application project and go to Project Properties, then Libraries and Classpath.

    The following libraries have now been added:

    • Application Core

    • BC4J Service Client

1. Start JDeveloper using the Oracle Fusion Applications Administrator Customization role.
2. Select the value for the layer in the Customization Context dialog that you want to customize. The following figure provides details.

   Figure 3-11 Customization Context Dialog

   
   Description of "Figure 3-11 Customization Context Dialog"
3. See Customizing and Extending SOA Components for instructions about customizing the SOA composite application during design time in JDeveloper and runtime with Oracle SOA Composer, Oracle BPM Worklist, and Oracle Enterprise Manager Fusion Applications Control.
4. When introducing new components, partner links, and SOA artifacts to the SOA composite application, add the XX prefix to the name to prevent problems with existing and future components that may be introduced in Oracle Fusion Applications patches.
5. Use the configuration plan that you extracted in Step 3 of Before You Start Using to Customize SOA Composite Applications. If any new partner links were added to your SOA composite application, add entries to the configuration plan, if needed. For information about configuration plans, see the "Customizing Your Application for the Target Environment Prior to Deployment" section of the Developing SOA Applications with Oracle SOA Suite.
6. Deploy the SOA composite application using the same revision you found in Before You Start Using to Customize SOA Composite Applications.