2Configuration Life Cycle

This chapter contains the following:

Overview of Configuration Life Cycle

All configurations and extensions must be done in a test environment. Typically, this environment contains one or more applications that will be moved to a production environment after you complete and test all configurations and extensions.

While using tools such as Page Composer, you must make application changes in a sandbox. Sandboxes store configurations in Extensible Markup Language files in a separate Oracle Metadata Services repository that's available only when you work in that particular sandbox.

Project managers can monitor and export configurations. Then, users can test the entire environment with all changes, as shown in the following figure.

Configuration workflow in a full test environment

Runtime Configurations and Extensions

Runtime Configuration Workflow

While using Application Composer and Page Composer to make runtime changes to your application, use sandboxes to save your changes in a segregated environment. For example, before making application changes, suppose you create a sandbox named MySandbox, and then make your changes in that sandbox. Now, if others want to see your changes, they can use MySandbox.

Note: If you have multiple users working on the same sandbox, then conflicts may arise within a sandbox. Hence, users must adhere to the prescribed guidelines to avoid such conflicts.

After you complete your application changes, others can review and approve your changes, and then publish to the test environment.

Note that a flexfield sandbox is for testing only and can't be published. Instead, you can deploy a flexfield to the test environment using the flexfield UI. To test a flexfield configuration before deploying it to the test environment, deploy it to a flexfield sandbox. The changes that you deploy to a sandbox are isolated from the test environment. Users who make the flexfield sandbox active in their session can only see these changes. After you're satisfied with the changes in the sandbox, you can deploy the changes to the test environment.

You can also use the Manage Configurations dialog box to:

  • View others' configuration metadata files

  • Download others' configuration metadata files for manually moving them to another environment or diagnosing any issues

Considerations for Viewing and Diagnosing Runtime Application Changes

Use the Manage Configurations dialog box to view and diagnose runtime changes made to application pages. Application changes are role-dependent and by default, the Manage Configurations dialog box displays the changes that the signed-in user had performed.

Before you begin viewing application changes, ensure that you have administrative privileges to access the Manage Configurations dialog box. If you're unable to display the page that contains the changes:

  1. Click your user image or name in the global header, and select Manage Configurations from the Administration menu.

  2. Use the Search text field on the Manage Configurations dialog box to search for the page, page fragment, or task flow.

You can view the application changes for a user in the Current Context column on the Manage Configurations dialog box. On this dialog box, you can change the page, page fragment, or task flow for which you're viewing application changes using the Search field.

Developers too may be assigned to specific roles and can view only those application changes that are permitted for the specific roles. However, administrators can view all application changes made at the site level, and for any user, in the All Layers column on the Manage Configurations page. To view application changes made by more than one user, administrators can select multiple users.

Page-Level Changes

To diagnose issues pertaining to application changes, determine whether changes have been applied to a page. Use the Manage Configurations dialog box to determine if page-level changes exist. If a page modification causes problems, such as a user interface component disappears from a page, you can export the application changes and examine the document file.

Sandboxes

Overview of Sandboxes

Sandboxes are testing environments that users can't see. Wherever possible, make changes to the application in a sandbox rather than making direct changes in the mainline environment. Sandboxes set apart untested configuration changes from the mainline environment. So you can test your changes in the sandbox and then publish it. After publishing, your changes become available in the mainline metadata or other sandboxes. So everyone can then see your changes in the environment. Mainline metadata is the primary branch of metadata a sandbox is published to.

Why You Need Sandboxes

Today's business landscape is quite dynamic. Companies are expected to respond quickly to address both customer and market needs. So multiple teams need to make application changes at the same time while sharing the same data model and configuration starting point. But you might get conflicts between teams working that way. To avoid such conflicts, sandboxes come in handy.

Sandbox Usage

You typically use sandboxes for either of these purposes:

  • Test-Only: You can make application changes using test-only sandboxes, which you don't want to publish to the mainline code.

  • Publish: Once satisfied with the application changes made in the test-only sandbox, you can replicate these changes in a sandbox that you want to publish, and then publish them to the mainline code. This sandbox type is also known as the integration sandbox because teams working in parallel, use this sandbox as the final staging point before publishing to the mainline code.

Note: Before each patch or upgrade, publish or delete your sandboxes. If you haven't yet completed your work, restart with a new sandbox.

You can apply different types of configurations to an application. For example, you can apply changes to an application's metadata stored in the metadata services repository or changes related to data security of the application. All such configurations are stored in sandboxes and are validated before applying them to an application.

Types of Configurations in Sandboxes

Sandboxes can contain the following types of configurations:

  • Metadata changes - These changes (such as non-flexfield user interface (UI) page changes) are captured in a metadata sandbox.

  • Data security changes - These changes are additionally captured in a data security enabled sandbox.

  • Changes in the generated flexfields business components - These changes are captured in a flexfield that's deployed as a single flexfield sandbox.

Once you're ready to make sandbox changes available in the mainline metadata, either publish the metadata or data security sandbox, or deploy the flexfield. You can download only metadata and data security sandboxes as a sandbox file for import to another application instance.

The following table lists the differences among the types of sandboxes.

Type of Changes Type of Sandbox Method for Making Changes Available in Mainline Metadata Downloadable?

Metadata

Sandbox

Publish sandbox

Yes

Data security

Sandbox enabled for data security changes

Publish sandbox

Yes

Flexfield

Flexfield deployed as a flexfield-enabled sandbox

Deploy flexfield

No

Only one sandbox can be active at a time. All changes made in an active sandbox are captured in that sandbox.

Environment

To make application changes in runtime, you must first create a sandbox and then use tools, such as Page Composer to make the changes. These changes remain within the sandbox and don't affect the mainline metadata. You must test and validate your changes in the sandbox. After testing, you can publish your sandbox to make the changes available in the production environment for other users.

Don't make application changes directly in the mainline metadata. Make all application changes in the sandbox first. When you make changes to an application at runtime in a sandbox, you isolate the changes from the mainline metadata. After completing the changes in the sandbox, verify them. When you're ready to save the changes, publish the metadata or security-enabled sandbox to the mainline metadata.

When you create a sandbox, you can see the information pertaining to only the existing application changes in the current mainline metadata. For example, suppose you make an application change in a sandbox and publish it. Then, on creating another sandbox for the next change, you will see the previous change in the new sandbox because that change exists in the current mainline metadata.

Flexfield sandboxes are for testing only and can't be published. Make flexfield configurations that are stored in a database. Then, deploy those configurations to a sandbox to see the resulting deployment artifacts in a sandbox environment. Flexfields are deployed directly to the mainline metadata using the flexfield user interface.

Tools

You can use several runtime configuration tools to make application changes. For example, you can modify objects and pages using Page Composer, which uses sandboxes. Oracle Business Process Composer and Oracle SOA Composer are also tools used for making runtime application changes, but they don't use sandboxes. They have their own mechanisms for handling application changes.

Managing a Flexfield Sandbox

To create a flexfield-enabled sandbox, deploy a flexfield to a sandbox using the Manage Flexfield task flow. The flexfield sandbox gets its name from the flexfield you deploy. You can't test two flexfields in the same sandbox. After deploying a flexfield as a sandbox, sign out and sign in again to view how the sandbox runtime reflects the flexfield changes, such as new segments. You can redeploy the same flexfield to the same sandbox repeatedly as you make incremental changes to the flexfield setup. A flexfield sandbox can't be published. So, when the flexfield is deployed to the mainline metadata, any page changes or data security in the flexfield sandbox can't reach the mainline metadata. If you're entitled to do so, manage flexfield-enabled sandboxes in the Sandboxes UI.

Guidelines for Working with Sandboxes

In the runtime configuration workflow, use sandboxes to isolate the changes from the mainline metadata for testing and validating. After you're satisfied with the changes, you can publish the changes back to the mainline metadata.

The testing sandboxes are never published and therefore produce no concurrency conflicts between sandboxes. You can have several testing sandboxes at the same time.

Application changes in the sandboxes that are published are merged back to the mainline metadata. This figure illustrates the two types of sandboxes and their relationship to the mainline metadata.

Types of sandboxes

Working with a Single Sandbox

Conflicts may arise when users edit a shared artifact, such as when a user performs an operation that adds or edits a translatable string. For example, suppose:

  • One user edits a field's display label or help text, or a validation rule's error message. Whereas, another user performs an operation at the same time that similarly affects translatable strings.

  • Two or more users are working in Navigator menus that are shared across applications. Whenever a conflict arises among users, the application displays concurrency warning messages.

Working with Multiple Sandboxes

Multiple sandboxes are used when configurations are stored in testing as well as production sandboxes. Suppose, after you create a sandbox, a concurrent change is made in the mainline metadata. Now, when you attempt to publish that sandbox, the application detects such conflicts at publication time, and you get error messages. For example, when you try to publish your sandbox, you may get a message showing a conflict on oracle/apps/menu/fnd/applcore/dataSecurity/dataSecurityService/mds/DSMO.xml. This message indicates that the security changes that you made in your sandbox conflict with other security changes in the mainline metadata. Delete the sandbox and recreate your changes in a new sandbox.

If multiple users are permitted to work in multiple sandboxes at the same time, follow these guidelines to avoid conflicts:

  • Any number of test-only sandboxes can operate 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 aren't published, cause no conflicts with each other. Be aware, however, that all modifications will be lost when the sandboxes are deleted.

  • For sandboxes that aren't for test-only and will be published, users can use multiple concurrent sandboxes only if they operate on mutually exclusive artifacts. For example, you can have:

    • One sandbox that contains a page that a user is modifying to add a task flow

    • Another sandbox that contains a different page from a different application

    However, some objects might still share underlying artifacts, and thus it's not always obvious if two objects are truly mutually exclusive. Thus, proceed with caution when using multiple concurrent sandboxes that will be published. It's still possible that a conflict could occur, which would require the deletion of one or more sandboxes.

  • Suppose the users update an artifact in both, the mainline metadata and in one sandbox, or in two different sandboxes. Now, when you publish the sandbox, the application detects such conflicts and you get an error message. At this point, cancel publishing the sandbox to avoid overwriting previous changes.

Note: For a sandbox that contains configurations pertaining to ADF Business Components, sign out and sign in again after switching in or out of this sandbox. This process ensures avoiding any inconsistencies between the runtime caches and the ADF Business Components definitions.

Create and Activate Sandboxes

To make changes to the application artifacts, you must first store them in an active sandbox. You can either create a sandbox or select an existing sandbox, and designate it as an active sandbox. The active sandbox holds the context for all the changes. The sandbox uses a database to store the actual changes. After testing your changes, you can publish the sandbox, or deploy the flexfield, and the changes are merged into the mainline metadata. Eventually, the sandbox is archived.

This procedure is for setting up non-flexfield sandboxes. For flexfields, use the Manage Descriptive Flexfields task or the Manage Extensible Flexfields task.

To create and activate a sandbox:

  1. Click your user image or name in the global header, and select Manage Sandboxes from the Administration menu.

  2. Use the Manage Sandboxes dialog box to create a sandbox.

  3. Click Save and Close.

  4. On the Manage Sandboxes dialog box, select the new sandbox or an existing one, and click Set as Active. The sandbox is designated as the active sandbox.

  5. Close the Manage Sandboxes dialog box.

    Only one sandbox can be active at a time. Once a sandbox is active for your session, the sandbox name is displayed on the sandbox bar above the global header.

After completing the application changes in the sandbox, publish them to make them available in the application for all others.

Before you start publishing your sandbox, test or validate your changes. If you made application changes using Page Composer, don't forget to close it while testing.

  1. Click your user image or name in the global header, and select Manage Sandboxes from the Administration menu.

  2. On the Manage Sandboxes dialog box, select the sandbox and click Publish. The Publish confirmation message box appears.

  3. Click Yes. The sandbox is published to the mainline metadata.

  4. Close the Manage Sandboxes dialog box.

Migration

Use the Migration page to create a set of all configurations and extensions made to an environment. Then, download the configuration set and upload it into another environment. The configuration set includes configurations across all product families. To open the Migration page, select Configuration > Migration from the Navigator menu.

Contents of the Configuration Set

The configuration set includes, but isn't limited to:

  • Application changes done using Application Composer, except the following changes:

    • Object artifacts that were generated from the Import and Export page in Application Composer to make extensions available for importing and exporting

    • User names and passwords for secured SOAP web service connections

    • The enabled attachment feature for custom objects

  • Changes made to application artifacts using the following tools:

    • Page Composer

    • Appearance

    • Structure

    • User Interface Text

    • Page Integration

  • Changes in the following artifacts of the Applications Core Setup application:

    • Messages

    • Lookups

    • Data security

    • Descriptive, extensible, and key flexfields, and value sets

    • Attachment categories and metadata

    • Deep Links

  • Changes in Reports and Analytics such as regeneration of SOAP services, including user-defined attributes

  • Changes in CRM email templates created in Application Composer

  • Changes done using the Manage Oracle Social Network Objects task

  • Changes in functional security settings made in Application Composer, including functional privileges that control access to custom objects. But the following security changes are not included in the configuration set:

    • Enterprise roles made directly in the security console

    • New duty roles made directly in the security console

    • Role hierarchy changes made directly in the security console

    • Custom roles created outside of Application Composer

    • Entitlements or privileges created outside of Application Composer

    Note: If functional security associated with roles in the source are migrated to a target instance, and the corresponding role doesn't exist in the target instance, an error will occur on import. If this is the case, you can selectively create these roles in the target environment when you import your configuration set, to avoid this errors.

The configuration set may also include:

  • Changes in Enterprise Scheduler Service (ESS) module, such as:

    • Job definitions

    • Job sets

    • Job schedules

    • Incompatibilities

    • Work shifts

    • Work assignments

    • Work assignment schedules

    • Job request parameters

  • Changes in Service Oriented Architecture (SOA) artifacts such as configurations done using SOA Composer

  • Changes done using Oracle Business Intelligence Enterprise Edition, including but not limited to:

    • Oracle Business Intelligence Answers

    • Oracle Business Intelligence Delivers

    • Business Intelligence Composer

    • Dashboard Builder

    • Oracle Business Intelligence Publisher

    Note: You can move the configurations done using the business intelligence tools only if the Business Intelligence in Configuration Set Migration Disabled profile option is set to No.

The configuration set doesn't include personalizations.

While an upload or restore activity processes Presentation Services changes, the following can occur:

  • Reports that were submitted by Oracle Enterprise Scheduler to Oracle Business Intelligence Publisher and were scheduled to execute during the process, will fail.

  • The Reports and Analytics pane may not display.

  • Oracle Business Intelligence Publisher reports may not display on Oracle Business Intelligence Presentation Services analyses or dashboard pages.

  • Users may not be able to access Oracle Business Intelligence Enterprise Edition features, such as:

    • Oracle Business Intelligence Answers

    • Oracle Business Intelligence Delivers

    • Business Intelligence Composer

    • Oracle Business Intelligence Interactive Dashboards

Note: To prevent including in-progress configurations in the configuration set, make your changes in a sandbox. The configuration set doesn't include changes from a sandbox until the sandbox is published.

You can use the Configuration Set Migration page to move configurations and extensions from any source environment to any target environment. However, you must always make configurations and extensions in a test environment. Then use the Configuration Set Migration page to move these configurations to a production environment. As configuration set migration doesn't provide a merge capability, never configure or add artifacts in a production environment. When you import a configuration set, the rows in the database that are not preconfigured are updated if a matching record exists. Otherwise a record is inserted.

The configuration set doesn't include all deletions. For example, the set does not include the removal of a configuration document using the Manage Configurations dialog box. After you import a configuration set into the target environment, you must examine the environment for any deletions that you must make manually. Similarly, the configuration set does not include roles or role hierarchy changes. Changes made to Security Console have to be manually updated in the target environment.

Create a configuration set to move configurations across all product families from the test environment, which is the source environment, to the production environment, which is the target. You can export all configurations, such as those stored in Oracle Metadata Services repository, JEDI, CRM, and BI using the Outgoing tab of the Migration page. You can then import them to the target environment using the Incoming tab. You can use a configuration set to move configurations in a batch instead of moving them individually. Each time you run the migration process in an environment, it copies not just the changes that you have recently made, but all of the configurations published in the environment.

Before You Start

Before creating a configuration set, ensure that:

  • The source and target application environments are of the same release and the same standard and one-off patches are applied to both environments.

  • All Page Composer configurations made in sandboxes are complete before they're published. Before starting the export process, you must publish all complete configurations.

  • All configurations and extensions made using the Structure page, the Manage Standard Lookups task, and Security Console, are complete.

  • To move content created using Oracle Business Intelligence Enterprise Edition features, the Business Intelligence in Configuration Set Migration Disabled profile option is set to No in source and target environments. To view this profile option, open the Manage Administrator Profile Values task in the Setup and Maintenance work area.

  • You have been granted the following privileges, so that you can access the Migration page:

    • Manage Outgoing Configuration Set

    • Manage Incoming Configuration Set

    Contact your security administrator for details.

  • You never make changes in the target or production environment while applying configurations.

Note: If you make changes to the production environment in emergency circumstances, you must make the same changes to the test environment. Making the changes to the test environment ensures that these changes are included in the next configuration migration.
  • You don't perform configurations in the source environment during the export process.

  • You delete any temporary files on the server from previous migrations. If there are temporary files on the server, click the Delete button next to your previous import and export records.

Create Configuration Sets

  1. In the source environment, select Configuration > Migration from the Navigator menu.

  2. Click Create Configuration Set on the Outgoing tab of the Migration page.

  3. Provide a name for the configuration set.

  4. Optionally, type a description of the configuration set.

  5. Select the content you want to migrate. The choices available on this screen are filtered by the offerings you have opted in for.

    Note: The Industry solution extensions module is for Oracle's internal use only and has no impact on migration.
  6. Click Save and Close.

  7. Click Refresh periodically to see the current status of the set creation because creating a configuration set can take a few minutes. You can click Log to review the process log, which provides more details about the configurations that are being compressed. If an error or exception occurs during this process, the log will give you information about the configurations that failed to compress. The process runs asynchronously, so you can close the page and return to it later.

  8. Eventually, the status changes to Ready for Download, which means that the configurations are ready for you to download. Before downloading the configurations, you can click Content Read Me to download the Readme file listing all the configurations you exported.

  9. Click Download to download your configuration set. Ensure that the downloaded file is a JAR file.

  10. After you download the file on your local file system, click Delete to remove the temporary files that were created on the server.

Apply Configuration Sets

After you apply configurations, end users must sign out and sign in again to see the changes. Hence, apply configurations when fewer people are signed into the environment. To apply configurations to the target environment, follow these steps:

  1. Open the Migration page in the target environment.

  2. Click the Incoming tab.

  3. Click Browse, specify the name and location of the configuration set file, and click Open.

  4. Once the status for the configuration set on the Incoming page is Ready to Apply Configurations, review the roles in your configuration set that are missing in your target environment. Create any missing roles as required. To review and create these roles, follow these steps:

    1. Click Details.

    2. Select an application.

    3. Select the roles you want to create.

    4. Click Create Role, and click Yes.

    5. Click OK after the roles are created.

    6. Click Save and Close.

  5. Click Apply to apply the configuration set to your target environment.

  6. Periodically, click Refresh to view the current status of the Apply action. You can review the process log, if required.

    The process runs asynchronously, so you can close the page and return to it later. When the configurations are applied, the status is displayed as Applied and Deleted.

    If problems occur during an Apply action, log a service request using My Oracle Support at https://support.oracle.com.

  7. The configuration set is successfully applied to the target environment when the status changes to Applied and Deleted.

Post Migration Tasks

Do these tasks after you apply your configuration set to the target environment:

  1. Access the target environment and examine the environment for any deletions that you must manually make.

  2. Deploy all flexfields that display a Patched status.

  3. Perform the following steps to send the new and updated social network definitions to the social network server:

    1. In the Setup and Maintenance work area, open the Manage Oracle Social Network Objects task.

    2. As part of the applying configurations process, some objects are created or updated. If the Enabled value of such an object is anything other than No, trigger the process of sending its definition to the social network server. You can do this by disabling the object and enabling it again with its original status. For example, if the Enabled value is Manual, then:

      1. Disable the object.

      2. Enable the object, and select the value, Manual.

      3. Click OK and save the changes.

    3. On the Manage Oracle Social Network Objects page, click Synchronize to synchronize a selected object, or click Synchronize All to synchronize all objects together.

  4. Manually migrate all business processes created in the source environment to the target environment.

  5. After applying configurations, perform functional testing to verify the changes. Suppose testing exposes problems with the configurations, such as importing more than you intended, or the changes weren't what you expected. In such cases:

    1. Open the configuration set in the Incoming tab or infotile of the Migration page.

    2. Click Restore to revert to the state before the configuration set was applied.

  6. Finally, broadcast information to the users that they must sign out and sign in to view the most recent changes.

Things to Know About Migration

  • After an environment upgrade, any previous imports which were performed in an earlier release can't be reverted. However if a new import is submitted in the upgraded instance, then the most recent import can be reversed.

  • Lookup values for lookup fields that exist in both source and target aren't overwritten during the configuration import. The lookup values from source are added to the target and all the lookup values coexist for the same field. For example, the Status field in its source environment has values, Open and Closed. In the target environment this field has values, Yes and No. After the import, the Status field in the target environment has values, Open, Closed, Yes, and No.

  • During configuration import, the data security privileges aren't automatically revoked in the target environment. For example, say a specific privilege is granted in the target environment, but the corresponding privilege doesn't exist in the source environment. During import, the privilege in the target environment won't be automatically revoked. To address this issue manually, add such a privilege to the source environment and revoke it. The revoke action is picked up as a configuration instance during the configuration import process and applied to the target environment.

  • You can create reports directly in the target environment. However, ensure that you create the reports and reference them to subject areas that were created in the source environment. Don't create subject areas directly in the target environment.

  • You can initiate configuration export and import tasks only from the mainline metadata. If you initiate migration from a sandbox, the process doesn't execute.

Caution: All user personalizations that are performed after a configuration set is applied are lost when you perform a restore action on that configuration set.

Considerations for Exporting and Moving Configurations

Configurations are stored in XML files. You can use these XML files to export configurations for the following reasons:

  • To move configurations and extensions to another environment, such as the production environment.

  • To diagnose issues noticed in the test environment.

  • To send files to your help desk for further diagnosing.

The following table lists the tools to use to export and move configurations and extensions.

Tasks Tools to Use

Move all configurations to another application environment.

Configuration Set Migration.

Move only descriptive flexfield configurations to another application environment.

Setup and Maintenance work area. Moves configurations for a specified module.

To move configurations for all modules, use Configuration Set Migration.

Move only extensible flexfield configurations to another application environment.

Setup and Maintenance work area. Moves configurations for a specified module.

To move configurations for all modules, use Configuration Set Migration.

Move only value set configurations to another application environment.

Setup and Maintenance work area. Moves configurations for a specified module.

To move configurations for all modules, use Configuration Set Migration.

Move only lookups to application environment.

Setup and Maintenance work area. Move application standard lookups, application common lookups, or both.

Move only data security policies to another application environment.

Setup and Maintenance work area.

It doesn't move Oracle Fusion Human Capital Management roles.

Export configurations to a file to help diagnose an issue.

Manage Configurations dialog box.

Downloading Configurations

Use the Manage Configurations dialog box to download configuration files for a given page. You can also upload the files into the Oracle Metadata Services repository using the same dialog box. To open Manage Configurations dialog box, click your user name in the global header, and select Manage Configurations from the Administration menu. You can use these files for diagnosing configuration issues.

You can also download all configurations of a page for all layers using the Download Configuration for All Layers link. This link is located at the bottom of the Manage Configurations dialog box. The file you download contains all the configuration XML files for the page. However, you can't upload this file anywhere.

Downloading Configuration Set Reports

After exporting configurations, you can view and download a configuration set report that contains a list of all configurations available in a configuration set. To do so, click Content Read Me from the Outgoing tab of the Configuration Set Migration page. To open the Configuration Set Migration page, select Configuration > Migration from the Navigator menu.

This report includes all new or updated:

  • Objects

  • Fields

  • Pages

  • Business intelligence (BI) changes

Business logic changes such as Groovy scripts and triggers aren't included in the configuration set report.

View and Delete Configurations

Use the Manage Configurations dialog box to view the changes made to the application pages and to delete unwanted changes. Click your user image or name in the global header, and select Manage Configurations from the Administration menu.

Deleting Configurations

To delete configurations:

  1. On the page that contains the configurations, select the page fragment or task flow, and then select Manage Configurations from the Administration menu.

  2. In the Name list, select the correct layer, and find the page, task flow, or fragment that contains the configurations.

  3. Click Delete for the configuration document that you want to delete.