2 Understanding the Customization Development Lifecycle

This chapter discusses the typical workflow for customizing Oracle Fusion Applications.

This chapter contains the following sections:

• Section 2.1, "Understanding Typical Customization Workflows"

• Section 2.2, "Using the Sandbox Manager"

• Section 2.3, "Using Customization Manager to Manage Runtime Customizations"

2.1 Understanding Typical Customization Workflows

All customizations and extensions, whether done by analysts or developers should be done in a testing environment. Typically, this environment contains one or more Oracle Fusion Applications that will then be moved to a production environment, once all customizations and extensions are complete and tested. Business analysts using Oracle Composer and CRM Application Composer can do their customizations in sandboxes that can be test only (that is, the code in the sandbox is for testing only, and is never deployed), or they can be done in a sandbox that is then published to the environment. Developers using design time tools, such as JDeveloper, deploy their customizations either directly to that environment, or they can publish to a sandbox. Project managers can monitor the customizations, and can also import and export customizations. The entire environment with all customizations can then be tested, as shown in Figure 2-1.

Figure 2-1 Customizations are Done in a Test Environment That Runs Oracle Fusion Applications

Tip:

When you extend Oracle Fusion applications, you may want those extensions to be configurable using Oracle Fusion Functional Setup Manager. For more information about creating setup flows for extensions, see the Oracle Fusion Applications Information Technology Management, Implement Applications Developer Guide.

2.1.1 Typical Runtime Workflow

CRM Composer and Oracle Composer make use of sandboxes. Sandboxes allow customizers to make their changes in a segregated environment. Sandboxes keep the customization XML files stored in an MDS repository that is only available when you choose to work in that particular sandbox (this repository is separate from the repository that holds customizations). For example, you might create a sandbox named MySandbox. When you go to make your customizations, you would first choose to do so within MySandbox. If you want other users to be able to see the customizations, they can then also use MySandbox, and the customizations will be there.

Note:

There are restrictions for when more than one user is working in a sandbox. For more information, see Section 2.2.1, "Sandboxes and Concurrent Usage."

You can also create a sandbox when you create security policies for custom objects that you have created using CRM Application Composer. These security sandboxes create new database tables to store the security information, and these tables are only available when you choose to work in that sandbox.

Once customizations in a sandbox are complete, the sandboxes can be reviewed and approved by others, and once approved, published to the full test environment where they become part of that repository. For more information about sandboxes, see Section 2.2, "Using the Sandbox Manager."

For flexfields, if you want to test the flexfield configuration before deploying it to the full test environment, you can deploy the flexfield to a flexfield sandbox. The changes that you deploy to a sandbox are isolated from the full test environment and can only be seen by those who make the flexfield sandbox active in their session. Once you are satisfied with the changes in the sandbox, you can deploy the changes to the full test environment.

When a sandbox is published, it is labeled. Labeling can act as a save point, meaning that if a future customization causes issues, you can use Customization Manager to promote the last known good label back to the tip (thereby removing all customizations done after that point). You can also use Customization Manager to view others' customization metatdata files, and to download those files to manually move them to another environment or to diagnose any issues. You can also upload others' customization metadata files to your environment. For more information, see Section 2.3, "Using Customization Manager to Manage Runtime Customizations."

Figure 2-2 shows the flow for a typical runtime customization process. Note that because customizing the Navigator menu, BPMN process flows, and reports does not use the MDS repository, customization of those artifacts is not shown in the flow. Refer to the corresponding chapters for those processes for more information.

Figure 2-2 Typical Runtime Customization Workflow

2.1.2 Typical Design Time Workflow

When your customizations cannot be done using a runtime tool, you often need to use JDeveloper to make your changes. Once you create your customizations, you can test them locally in JDeveloper, and when complete, deploy them directly into the full test environment. You can also deploy your customizations to a sandbox (security customizations done at design time are not saved to a sandbox). Additionally, you can use source control software to manage these changes. For more information about what source control software JDeveloper supports, see the "Versioning Applications with Source Control" topic of the JDeveloper online help.

Because your changes (other than security changes) are stored in customization files in MDS, these changes can also be viewed and managed using Customization Manager. However, they cannot be promoted as the customizations made in Oracle Composer can be. You need to undeploy changes that are causing issues, fix the issues, and then redeploy to the test environment.

Figure 2-3 shows the flow for a typical design time customization process.

Figure 2-3 Typical Design Time Customization Workflow

2.2 Using the Sandbox Manager

You can make changes to an application at runtime in a sandbox so that the changes are isolated from the mainline. The mainline is a branch of data that serves as a single source of truth. Once you are satisfied with the changes in the sandbox and want to commit the changes, you can publish the MDS or security-enabled sandbox to the mainline. Flexfield sandboxes are for testing only and cannot be published. You make flexfield configurations that are stored in a database and then you can deploy those configurations to a sandbox to see the resulting deployment artifacts in a sandbox environment. Flexfields are deployed directly to the mainline using the flexfield UI. For more information about flexfields, see Section 5.6, "Deploying Flexfield Configurations."

You can use runtime tools to customize the application. The sandbox manager works with CRM Application Composer and Oracle Composer to customize objects and pages.

• For information about using CRM Application Composer, see Chapter 4, "Customizing Objects."

• For information about using the Oracle Composer, see Chapter 3, "Customizing Existing Pages."

Oracle Business Process Composer and Oracle SOA Composer are also runtime customization tools, but do not use the sandbox manager. They have their own mechanisms for handling customization changes.

• For information about using Oracle Business Process Composer, see Chapter 7, "Customizing and Extending BPMN Processes ."

• For information about using SOA Composer, see Chapter 12, "Customizing and Extending SOA Components."

To customize an Oracle Fusion application, you first create a sandbox and then use Oracle Composer or CRM Application Composer to make the customizations. These changes will be contained within the sandbox so they don't affect the mainline. You then test and validate the changes by publishing the sandbox to the full test environment. After the application has been tested, it can then be moved to the production environment where the customization changes will be available to users of the system.

The sandbox manager is a tool for managing the different types of customization changes that can be applied to an application. The different types of sandboxes are:

• Metadata

  The metadata sandbox supports making changes to the application's metadata stored in the MDS.

• Security

  The security-enabled sandbox supports making data security changes.

• Flexfield

  The flexfield sandbox is not created in the sandbox manager. You would use the flexfield UI to make changes to the flexfields and then deploy the flexfield to the sandbox. The flexfield deployment process manages the creation of the sandbox. For more information about flexfields, see Section 5.6, "Deploying Flexfield Configurations."

With the exception of security, the sandboxes created using the sandbox manager are also available in JDeveloper when you use JDeveloper to create and deploy customizations intended for a deployed Oracle Fusion application in WebLogic Server. The available sandboxes will appear in a selection list in JDeveloper during deployment. For more information, see Section 11.11, "Deploying ADF Customizations and Extensions."

In CRM Application Composer, when users want to customize security, they can do so using a sandbox specifically for editing security policies. When the user enables the security sandbox, the operation will duplicate the schema for Oracle Fusion Data Security tables and is therefore a lengthy setup operation. Before users enable the security sandbox, they should wait until they are ready to make security policy customizations. The security policy customizations that users publish from a sandbox will be merged into the Oracle Fusion security policy repository as part of the native application and overwrite any previous customizations. Because inconsistencies can result when multiple users edit the security policies associated with the same object in different sandboxes, users should coordinate so they avoid editing the same object concurrently.

The metadata and security sandbox sessions can be saved and be downloaded as a file to be imported into other Oracle Fusion applications.

2.2.1 Sandboxes and Concurrent Usage

In the customization runtime workflow, sandboxes are used to isolate the changes from the mainline for testing and validating. After you are satisfied with the changes, you can publish the changes back to the mainline. You can also create sandboxes for testing purposes only, and not publish them.

There are two types of sandboxes:

• Sandboxes intended to be published.

  These sandboxes will be merged back to the mainline code.

• Sandboxes intended for "test-only" purposes.

  These "test-only" sandboxes will not be published and therefore produce no concurrency conflicts between sandboxes. You can have many "test-only" sandboxes at the same time. But if you have multiple users working on the same "test-only" sandbox, they will still need to adhere to the guidelines described in Section 2.2.1.1, "Guidelines for One Sandbox, Multiple Users."

Figure 2-4 illustrates the two types of sandboxes and their relationship to the mainline.

Figure 2-4 The Two Types of Sandbox Usages

An application artifact typically includes several metadata files. Therefore, creating or editing an artifact usually means making changes, whether directly or indirectly, to more than one file. Some of these metadata files may be shared between artifacts.

When multiple users can customize an application using sandboxes, there are two types of concurrency conflicts:

• Conflicts within a sandbox: Users overwriting changes created by other users, either directly by changing the same artifact, or indirectly by affecting files that are shared between the artifacts.

• Conflicts between sandboxes (intended for publishing only): Multiple sandboxes with the same customized artifact publishing to the mainline.

Note:

Because many customization scenarios, including customizing security policies, involve editing the same underlying artifacts, the only way to be certain of eliminating the possibility of any concurrency conflicts is to allow only one user at a time in an active sandbox. If you must have multiple users or multiple sandboxes, you should adhere to the usage guidelines described in Section 2.2.1.1, "Guidelines for One Sandbox, Multiple Users," and Section 2.2.1.2, "Guidelines for Multiple Sandboxes, Multiple Users."

Conflicts within a sandbox can arise when multiple users are customizing an application using the same sandboxes at the same time, because more than one user may be attempting to customize the same artifact, or performing a customization task that indirectly affects other shared files. An example of a direct conflict is when different users attempt to customize the same page, the same fragment, or the same metadata file in the same layer. An example of an indirect conflict is when two users, each creating their own object, cause a conflict in the metadata file that tracks which new objects have been created by both saving their changes around the same time.

Conflicts may also arise when users are editing a shared artifact, such as when a user performs an operation that adds or edits a translatable string. For example, a user edits a field's display label or help text, or a validation rule's error message, while another user performs an operation around the same time that similarly affects translatable strings. Another example of a shared artifact conflict is when two or more users are working in navigator menus which are shared across applications.

When you are using Oracle Composer, although you are not required to, you should use a sandbox. Oracle Composer provides concurrency warning messages when there is a potential customization conflict with another user. For Oracle Composer, these warning messages help prevent conflicts. For more information, see the "Editing Pages" section of the Oracle Fusion Middleware User's Guide for Oracle WebCenter Spaces.

When you are using CRM Application Composer, you should always use a sandbox. CRM Application Composer provides error messages when a concurrency conflict is encountered. If multiple users in a single sandbox attempt to edit the same artifact, an error message is displayed. For example, if two users are editing the label of the same attribute, CRM Application Composer will display an error message.

Conflicts between sandboxes can arise when there is more than one sandbox intended for publishing in use. If two sandboxes contain customization changes to the same artifact and both are being published, the sandbox that is being published last is given an option (by the sandbox manager) to overwrite the changes for that artifact from the sandbox that was published first. If the user working in the second sandbox decides to force-publish the second sandbox, it will overwrite the changes published by the first sandbox. These types of conflicts can also occur with shared metadata files such as resource bundles that store translatable strings.

If there is a concurrent change made in the mainline code after the sandbox was created and the user attempts to publish that sandbox, such conflicts are detected at publish time and errors are raised.

2.2.1.1 Guidelines for One Sandbox, Multiple Users

Regardless of whether the sandbox is intended for publishing or whether it is for "test-only," if you need to have multiple users working in a single sandbox, you should follow these usage guidelines:

• Multiple concurrent users in the same sandbox should operate only on different and unrelated objects.

  For example, if user1 updates object1, then user2 can update object2 but should not update object1. Be aware that if both modifications involve changes to translatable strings, then saving changes to separate objects around the same time may still cause a conflict in the resource bundle that stores the translatable strings.

• If multiple users do update the same artifact concurrently (either the same object or the same underlying frequently modified file), they will get a concurrent update error. In this case, the second user's changes will not be saved (the Save button will be disabled) and one of the users will have to cancel and try again.

  CRM Application Composer will retain any uncommitted changes in the UI. For example, if the user were editing a groovy expression when the error was encountered, the expression will be retained in the editor so the user can copy and paste the expression to try customizing again. (No metadata corruption or partial transaction commits will happen.)

• Users in the same sandbox will see the changes created by one another. The latest version of each object gets loaded on-demand the first time it is viewed in CRM Application Composer. Users can refresh their view to the latest definition from MDS and see the changes listed in the tree structure at the left side of the CRM Application Composer UI. However, if there are ADF Business Components customizations, users may need to log out and log back in again to see those changes reflected in the UI.

2.2.1.2 Guidelines for Multiple Sandboxes, Multiple Users

If you need to have multiple users working in multiple sandboxes, you should follow both the guidelines in Section 2.2.1.1, "Guidelines for One Sandbox, Multiple Users," and these usage guidelines:

• There can be any number of "test-only" sandboxes operating concurrently. That is, multiple users can use multiple sandboxes concurrently for testing if these sandboxes will never be published. Sandboxes that are used for testing only, and that are not published, cause no conflicts with each other. Be aware, however, that all modifications will be lost when the sandboxes are destroyed.

  Note:

  Even though sandboxes that are for "test-only" cause no conflicts with each other because they are not published, multiple users who work in the same "test-only" sandbox still need to follow the guidelines in Section 2.2.1.1, "Guidelines for One Sandbox, Multiple Users."

• For sandboxes that are not for "test-only" and that will be published, you can have multiple concurrent sandboxes only if they operate on mutually exclusive artifacts. For example, you can have one sandbox that contains a page that is being customized to add a task flow, and another sandbox that contains a different page from a different application.

  Note:

  For CRM Application Composer, you should have only one sandbox that is intended for publishing at a time. You cannot have multiple concurrent sandboxes that are intended for publishing. You can still have other sandboxes that are for "test-only."

• If an artifact is updated in both the mainline and in the sandbox (or two different sandboxes), when the sandbox is published, such conflicts are detected and an error is raised. At this point, administrators should cancel the publishing of the sandbox to avoid overwriting previous changes.

  Note:

  For a sandbox that contains ADF Business Components customizations, you should log out and log back in again after switching in or out of this sandbox to avoid any inconsistencies between the runtime caches and the ADF Business Components definitions.

2.2.2 Setting Up Sandboxes

When you create a sandbox, the currently available metadata is gathered into a sandbox session. You designate a sandbox to be the active sandbox by choosing either the newly created sandbox or select from a list of existing sandboxes in a table. The active sandbox is the context for all changes. Once activated, you can make customization changes to the application artifacts and these changes will be stored in the sandbox. The sandbox uses a database to store the actual change information. After you are satisfied with the changes, you can publish the sandbox, or deploy the flexfield, and the changes will be merged into the mainline and the sandbox archived.

To set up a sandbox:

1. Access the sandbox manager.

   For non-flexfield sandboxes, you can access the sandbox manager by selecting the Manage Sandboxes menu item from the Administration menu in the global area of Oracle Fusion Applications.

   Figure 2-5 shows the Manage Sandboxes menu selection from the Administration dropdown.

   Figure 2-5 Accessing the Sandbox Manager

   
   

   For flexfields, you need to be in the flexfield UI and then select the Deploy Flexfield to Sandbox menu item to deploy the customizations to a flexfield sandbox. Flexfield changes are stored in flexfield metadata in the mainline database and are only available to users when the flexfield is deployed, as described in Section 5.6, "Deploying Flexfield Configurations." Thus for flexfields, the remaining tasks in this procedure do not apply.

2. In the Manage Sandboxes dialog, you can create a new sandbox, select from a list of sandboxes in the Available Sandboxes page, import a sandbox as a file, or perform other sandbox functions. Figure 2-6 shows a Manage Sandbox dialog with one available sandbox.

   Figure 2-6 Manage Sandboxes Dialog

   
   

3. Create a new sandbox by clicking the New icon or selecting Actions > New.

4. In the Create Sandbox dialog, enter a name for the sandbox. If you want a security-enabled sandbox, select Create Data Security Sandbox and click Save and Close. Figure 2-7 shows the dialog with security enabled.

   Note:

   Because setting up the security sandbox requires duplicating the schema for Oracle Fusion Data Security tables, this will always be a lengthy operation in CRM Application Composer. Be sure to allow sufficient time for the process to complete and do not to terminate it early. You may want to defer customizing security and enabling the security sandbox until you are sure that you need to make customizations.

   Figure 2-7 Create Sandbox Dialog

   
   

   You will see a confirmation dialog when the sandbox has been successfully created. Click OK to dismiss the dialog.

5. Set the active sandbox. You can make the newly created sandbox or an existing sandbox the active sandbox.

   In the Manage Sandboxes dialog, in the Available Sandboxes page, select the sandbox you want to make active and click Set as Active as shown in Figure 2-8.

   Figure 2-8 Manage Sandboxes Dialog

   
   

   Only one sandbox can be active at one time. The customization changes are captured in the active sandbox.

6. Export a sandbox.

   A sandbox can be exported as a file for transporting, sharing, and other usages where packaging it as a file is required. Consequently, a sandbox exported as a file can be imported.

   In the Sandbox Details dialog, click Download All. Enter the location and file name for the exported sandbox.

7. Import a sandbox.

   In the Manage Sandboxes dialog, click Import.

   In the Import dialog, click Browse to navigate to the file or enter the fully qualified file name.

8. Exit the sandbox.

   Mouse over the sandbox name next to the Session Sandbox label in the global area of the Oracle Fusion Applications to launch a popup dialog. Click Exit Sandbox.

   Figure 2-9 Sandbox Popup Dialog

   
   

   In the Exit Sandbox dialog, click Yes.

   Figure 2-10 Exit Sandbox Dialog

   
   

2.2.3 Publishing Sandboxes

If there are changes to the mainline from another source and you publish your sandbox, the mainline is not overwritten. If there are conflicts, you will be warned and will be given a choice to fix the conflicts.

To publish a sandbox:

1. Make the customization changes to the application by going to the various customization environments. For example, you can create new objects and customize the objects in CRM Application Composer.

   You can make metadata changes in the sandbox. Metadata changes are normally associated with MDS. These include making changes to a page, to ADF customization, and to ADF business objects. For more information about making changes to the page, see Chapter 3, "Customizing Existing Pages." For more information about making changes to business objects, see Chapter 4, "Customizing Objects."

   You can make security changes by applying them to a security-enabled sandbox. You can test your security changes and policies before you publish the sandbox to commit the changes. For more information about customizing security policies, see Section 9.2, "Defining Security Policies for Custom Business Objects." For more information about custom business objects, see Chapter 15, "Customizing Security for ADF Application Artifacts."

2. Test or validate the changes in runtime using test or production systems and any combination of validation setups.

   In the Manage Sandboxes dialog, click on the sandbox link to launch the Sandbox Details dialog. You can view the layers and objects where you have made customization changes, as shown in Figure 2-11.

   Figure 2-11 Sandbox Details Dialog

   
   

3. Publish the sandbox to the mainline.

   After you are satisfied with the changes, select the sandbox and click Publish in the Manage Sandbox dialog or in the Sandbox Detail dialog to commit the changes to the mainline.

2.3 Using Customization Manager to Manage Runtime Customizations

When you have the correct privileges, you can use Customization Manager to view and diagnose customizations made for any page in an application. You can also use Customization Manager to move customizations to another environment, for example from one test environment to another.

Tip:

For more information about privileges, contact your security administrator.

2.3.1 Before You Begin Using Customization Manager

You need to do the following before you can use Customization Manager:

• You need to have specific privileges to access Customization Manager. Please contact your security administrator for details.

• To access Customization Manager, from Administration menu in the global area of Oracle Fusion Applications, choose Customization Manager

2.3.2 Viewing Customizations Using Customization Manager

Figure 2-12 shows Customization Manager with all artifacts related to the CustomerCtrWorkarea.jspx file.

Figure 2-12 Customization Manager

As shown, there has been a customization made to a page fragment file in the Site customization layer, and a customization made to the UIShell Page Template in the external layer. The customizations in the Current Context column show the customizations that the currently logged in user would see in a running version of the application. All customizations, including those the currently logged in user might not see (perhaps because of security policies), are listed in the All Layers column.

For example, say you are a customization developer. Because you as a user have been assigned a particular role, the page that you see will only display customizations appropriate for your role. Those customizations will be listed in the Current Context column (provided you chose the proper layer from the Layer Name dropdown menu). This helps you to determine what customizations are affecting what you are seeing. There may, however, be customizations you do not see. You can view those customizations from the All Layers column.

To view customizations:

1. Navigate to the page you wish to view customizations for.

2. From Administration menu in the global area of Oracle Fusion Applications, choose Customization Manager.

   Tip:

   Once you are in Customization Manager window, you can change the page for which you are viewing customizations using the Search field.

3. Change the layer values for the Current Context and All Layers columns as needed. For more information about customization layers, see Section 1.2, "Understanding Customization Layers."

   The Current Context column shows customizations affecting the page as the currently logged in user sees it. The All Layers column shows all customizations.

2.3.3 Downloading and Uploading Customization Files

As explained in Section 1.2, "Understanding Customization Layers," customizations are stored in an XML file. You can download the XML file for a customization to your local machine. You may need to do this for the following reasons:

• You need to diagnose issues seen in the test environment.

• You need to send files to Oracle Support for further diagnosing.

• You want to import a customization into another environment. For example, a customization developer using JDeveloper may need to see customizations done by someone else.

• You need to migrate a customization into a production environment.

Once you download customizations, you may then need to upload the revised files back into the environment. Or you may need to upload customization files into a new environment using Customization Manager.

Tip:

Customization Manager allows you to upload and download customization files for a given page at a time. If you need to upload or download customization files for multiple pages, then you can use WebLogic scripting tool commands or Fusion Middleware Control. For more information, see Section 10.2.4, "Importing Customizations into Your Workspace."

To download and upload customizations:

1. Navigate to the page for which you wish to download or upload customizations.

2. From Administration menu in the global area of Oracle Fusion Applications, choose Customization Manager.

   Tip:

   Once you are in the Customization Manager window, you can change the page for which you are viewing customizations using the Search field.

3. To download a file, click the Download link for the corresponding customization. The file will be downloaded to your local machine.

4. To upload a file, click the Upload link for the corresponding customization. In the Upload Customization dialog, click Choose File and navigate to and select the appropriate file. Click OK to upload the file.

   Note:

   The name of the file you upload must be the same as the name of the file you are replacing.

5. To download all customizations of the page for all layers, click the Download Customizations for All Layers link, located at the bottom of the window. This will download the AllCustomization.zip file, which contains all the customization XML files for the page.

2.3.4 Promoting a Customization to the Tip

When you save a customization in Oracle Composer, you can choose to save it to a label. You can think of a label as a "save point," that is, a point at which you know the customization works as expected. By having a label, if an issue occurs after the label, you can revert back to that label. To revert back to a label, you promote it to the tip.

Note:

You can only promote customizations done in Oracle Composer. Customizations done in a sandbox are automatically labeled when the sandbox is published. For more information about using Oracle Composer, see Chapter 3, "Customizing Existing Pages." For more information about sandboxes, see Section 2.2, "Using the Sandbox Manager."

To promote a customization to the tip:

1. Navigate to the page you wish to view customizations for.

2. From Administration menu in the global area of Oracle Fusion Applications, choose Customize page_name Pages to open the page in Oracle Composer.

3. In the tool bar, click Customizations Manager.

4. To promote a customization to the tip, click Promote for the corresponding artifact.

5. In the Promote Documents dialog, select the label that you want to promote to the tip and click OK.