12 Working With DAC Metadata Patches

The DAC metadata patch feature enables you to import and export subsets of DAC metadata at a fine grain.

This chapter contains the following topics:

• DAC Metadata Patching Scenarios

• DAC Metadata Patching Life Cycle

• Creating a DAC Metadata Patch

• Exporting a DAC Metadata Patch

• Applying a DAC Metadata Patch to the DAC Repository

• Exporting and Applying Patches Using the Command Line

DAC Metadata Patching Scenarios

You can use the DAC metadata patch feature in the following ways.

Patching Metadata Provided by Oracle

The DAC metadata patch feature works in conjunction with OPatch, an Oracle-supplied utility, to update the predefined (out-of-the-box) Oracle BI Applications metadata provided by Oracle. This approach applies to predefined containers only. You cannot modify the predefined Oracle BI Applications metadata in any way other than updating it with a patch from Oracle.

Note:

If you want to customize the predefined metadata, you must first make a copy of the predefined source system container. For more information about source system containers, see "About Source System Containers".

Distributing Metadata to Other Environments

You can use the patch feature to move subsets of data from one environment to another. For example, you can move issues fixed in a development environment to QA or production environments. This approach can be used with custom source system containers only and not with predefined (out-of-the-box) containers.

The section titled "DAC Metadata Patching Life Cycle" describes in detail the process for distributing DAC metadata to other environments.

DAC Metadata Patching Life Cycle

Figure 12-1 shows the process of distributing metadata to other environments. The steps in the process are as follows:

• Step 1: Create a new, empty patch. The DAC automatically assigns the patch version value as 1 and the status as Open. Open patches are listed in the Working Patches tab in the Setup view.

  For instructions on creating a patch, see "Creating a Patch".

• Step 2: Add contents to the patch. For information about what objects you can add to a patch, see "About Patch Contents". A patch must have an Open status in order for objects to be added or removed. The patch stores pointers to the repository objects.

  For instructions on adding contents to a patch, see "Adding Contents to a Patch".

• Step 3: Close the patch. When you change the patch status to Closed, the patch can no longer be edited. You can reopen a Closed patch in order to edit it. When you change the status from Closed to Open, the patch version is automatically incremented by 1. Closed patches are listed in the Working Patches tab.

  For instructions on closing a patch, see "Changing the Status of a Patch".

• Step 4: Export the patch. When you export the patch, the patch and its contents are stored in an XML file in a directory you specify.

  For instructions on exporting a patch, see "Exporting a DAC Metadata Patch".

• Step 5: Apply the patch to the DAC repository. When you apply a patch, the DAC repository is upgraded with the patch contents stored in the XML file. After the patch process, the patch status will be one of the following:

  • Complete. All objects were applied successfully to the DAC repository.

  • Incomplete. Some objects were applied successfully to the DAC repository and some objects were not applied.

  For information about why objects are not applied to the DAC repository, see "When Does a Patch Fail to be Applied to the DAC Repository?" Applied patches are listed in the Applied Patches tab in the Setup view.

  For instructions on applying a patch, see "Applying a DAC Metadata Patch to the DAC Repository".

• Step 6: Upgrade the data warehouse schema. If the patch contents included column-level changes, you need to upgrade the data warehouse schema with the same updates that were made to the DAC repository.

  For instructions on upgrading the data warehouse schema, see Chapter 10, "Managing Data Warehouse Schemas."

Figure 12-1 DAC Patch Process

Creating a DAC Metadata Patch

The process for creating a DAC metadata patch comprises the following steps:

• Creating a Patch

• Adding Contents to a Patch

• Changing the Status of a Patch

For a description of the complete DAC metadata patching life cycle, see "DAC Metadata Patching Life Cycle".

Creating a Patch

Follow this procedure to create a new patch.

To create a patch

1. In the Setup view, select the Working Patches tab.

2. In the toolbar, click New.

3. Enter a descriptive name for the patch, and then click Save.

   DAC automatically sets the status as Open and the Patch Version as 1.

Adding Contents to a Patch

You can add repository objects to patches in two ways:

• Adding contents by manual selection. Using this method, you manually select container-dependent and seed data objects you want to add to the patch. For instructions, see "Adding Contents to a Patch by Manual Selection".

• Adding contents based on a timestamp range. Using this method, you configure a period of time between two timestamps. All eligible objects that are new or changed between these two timestamps, in all source systems, will be added to the patch. For instructions, see "Adding Contents to a Patch Based on a Timestamp Range".

About Patch Contents

The objects listed below are eligible to be included as contents in a patch. You can manually select any of these objects to be included in a patch. Alternatively, if you choose to add contents based on a timestamp range, the objects from the list below that are new or changed in the timestamp range will be included in the patch.

• Container-dependent objects (objects visible in the DAC Design view)

  When you add a parent object to a patch, you can choose whether or not to add the child objects and extended properties. Table 12-1 lists the parent objects you can add to a patch as well as the child objects that will be added if you choose to add child objects.

  Note: When you add a child object to a patch, the parent object is automatically included as well.

  Table 12-1 Objects and Child Objects Added to Patches

  Parent Object Added to Patch	Child Objects Also Added to Patch
  Subject area	Configuration tags Tables Tasks
  Tables	Actions Columns Indexes Multi-Column Statistics Related tables
  Indexes	Actions Columns
  Tasks	Actions Conditional tables Configuration tags Extended properties Execution type Phase dependencies Parameters Refresh date tables Source tables Target tables
  Task groups	Child tasks
  Configuration tags	Subject areas Tasks
  Source system folders	Logical folders Physical folders
  Source system parameters	None
  Source system actions	None

  
  

• Seed data objects (objects defined or viewed by clicking Tools on the menu bar, and then selecting Seed Data)

  • Actions (index, task, table)

  • Execution types

  • Global external parameters

  • Heuristics

  • Logical data sources

  • Task logical folders

  • Task phases

  • Task physical folders

• Patches

  You can also add other patches to a patch. A patch added to another patch becomes the child patch. The parent patch is referred to as a cumulative patch. A cumulative patch can include both objects and other patches (including the patch contents).

Adding Contents to a Patch by Manual Selection

You can manually select any of the objects listed in the section "About Patch Contents" to be included in a patch. You can add objects to the patch from multiple source system containers.

To add contents to a patch by manual selection

1. Review the section "About Patch Contents" for information about which repository objects you can add to a patch.

2. Make sure the patch that you want to add contents to has the status Open. You can only add contents to an Open patch. If the patch is Closed, you can reopen it. For instructions, see "Changing the Status of a Patch".

3. To add a container-dependent object:

   1. Select the appropriate source system container from the drop-down list.

   2. Go to the appropriate tab, and query for the objects you want to add to the patch.

   3. In the list of query results, right-click, and select Add Object(s) to Patch.

   4. In the Patching... dialog, select one of the following:

      - Selected record only. To add only the selected record to the patch.

      - All records in the list. To add all the records in the list of query results to the patch.

   5. In the Patches dialog, click in the Select a Patch field, and then select the appropriate patch to which you want to add contents.

   6. In the Add to Patch Set area, select one of the following:

      - Selected parent record(s) only. To add only the parent objects to the patch without adding any child objects.

      - All related contents of the selected record(s). To add the parent objects and the child objects and extended properties to the patch.

4. To add a seed data object:

   1. On the Tools menu, select Seed Data, and then select the appropriate menu item.

   2. Right-click the object you want to add to the patch, and then select Add Object(s) to Patch.

   3. In the Patching... dialog, select one of the following:

      - Selected record only. To add only the selected record to the patch.

      - All records in the list. To add all the records in the list of query results to the patch.

   4. In the Patches dialog, click in the Select a Patch field, and then select the appropriate patch to which you want to add contents.

5. To add a patch (and its contents) to another patch:

   1. In the Working Patches tab of the DAC Setup view, select the patch that you want to add to another patch.

   2. Right-click, select Patches, and then select Add as Child Patch.

   3. In the Patches dialog, click in the Select a Patch field, and then select the patch to which you want to add the child patch.

6. A message dialog informs you which objects were added to the patch. Click OK.

7. To view the contents of the patch:

   • Click the Contents subtab to view container-dependent and seed data objects. Both parent and child objects are listed in the Contents subtab.

   • Click the Child Patches subtab to view child patches added to the patch. Only the patch (and not the patch contents) is listed in the Child Patches subtab. For nested patches—that is, a child patch that has its own child patch—only the immediate child patch is listed in the Child Patches subtab.

Adding Contents to a Patch Based on a Timestamp Range

You can add contents to a patch by configuring a period of time between two timestamps. All eligible objects that are new or changed between these two timestamps, in all source systems, will be added to the patch.

To add contents to a patch based on a period between two timestamps

1. Review the section "About Patch Contents" for information about which repository objects will be added to the patch.

2. Make sure the patch that you want to add contents to has the status Open. You can only add contents to an Open patch. If the patch is Closed, you can reopen it. For instructions, see "Changing the Status of a Patch".

3. In the DAC Setup view, select the Working Patches tab.

4. Query for the patch to which you want to add contents.

5. Right-click the patch, select Patches, and then select Add Objects to Patch (Time Range).

6. In the Patching... dialog, click in the From Timestamp field to open the Date dialog, and configure the beginning timestamp:

   1. Select a year, month and day.

   2. Select either AM/PM or 24 Hours to indicate the convention of time to use.

   3. Select the hour, minute, and second for the beginning timestamp.

   4. Click OK.

7. Click in the To Timestamp field, and configure the ending timestamp by following the substeps in Step 6.

8. To view the contents of the patch, click the Contents subtab.

Changing the Status of a Patch

After you have added contents to a patch, you need to change the patch status to Closed in order to export it. You can re-open a Closed patch if you need to add or remove objects. Each time you change the status from Closed to Open, the Patch Version value is incremented by one.

To change the status of a patch

1. Go to the Working Patches tab in the Setup view.

2. Query for the patch whose status you want to change.

3. Right-click, select Patches, and then select one of the following:

   • Re-Open Patch. Changes the status of Closed patches to Open.

   • Close Patch. Changes the status of Open patches to closed.

     The new patch status is displayed on the Status column of the Working Patches tab.

Exporting a DAC Metadata Patch

When you export a patch, the patch and its contents are exported from the DAC repository and saved in an XML file in a directory you specify. The XML file contains identifying information about the patch and the patch contents, including the repository object name, the object's source system container, and the parent object of child objects.

Note:

If you inactivate a patch content entry, the object will not be exported to the XML file.

To export a patch

1. In the DAC Setup view, select the Working Patches tab.

2. Query for the patch you want to export.

3. Make sure the patch status is Closed. If the patch is Open, you need to close it by following the instructions in "Changing the Status of a Patch".

4. Right-click the patch, select Patches, and then select Export Patch.

5. In the Save dialog:

   1. Select the directory to which you want to export the patch.

   2. In the File Name field, you can leave the default name of the file, which is in the format <patchName><version>.xml, or you can enter a new name.

   3. Click Save.

Applying a DAC Metadata Patch to the DAC Repository

When you apply a patch, the patch contents are applied to the DAC repository. You can re-apply a patch as many times as needed. The patch history is tracked by the patch version and timestamps for when the patch was closed, exported, and applied to the repository. This information appears in the Audit Trails subtab of the Working Patches tab.

To apply a patch to the DAC repository

1. On the Tools menu, select DAC Repository Management, then select Apply Patch.

2. In the Open dialog:

   1. Select the folder that contains the XML file you want to import.

   2. Select the XML file you want to import.

   3. Click Open.

3. A message dialog informs you whether the process was successful. Click OK to close the dialog.

   The applied patches are listed in the Applied Patches tab. The status of an applied patch can be one of the following:

   • Completed. All objects in the patch were successfully applied to the DAC repository

   • Incomplete. Some objects were successfully applied, but other objects failed to be applied.

   • Failed. No objects were applied to the DAC repository.

4. Update the data warehouse schema to reflect the patch applied to the DAC repository. For information about updating the schema, see "Creating, Upgrading or Dropping Subsets of Tables in the Schema for Oracle Databases".

   Note: You can only update the data warehouse schema with a subset of tables (tables included in a patch) if you are using an Oracle database for the data warehouse.

When Does a Patch Fail to be Applied to the DAC Repository?

Patches can fail to be applied to the DAC repository for the following reasons:

• The container name in the XML file does not match the container name in the DAC repository.

• An object in the XML file has a container name that does not exist in the DAC repository.

Object Ownership During the Patching Process

Objects included as patch contents will maintain their ownership state. For example, original objects will be applied to the target repository as originals, clones as clones, and references as references. However, if objects in a customized source system container are updated by a patch, they become cloned objects. If the objects do not already exist, they will be applied to the repository as original objects. The properties of objects in the XML file will take precedence over those in the target repository. That is, if objects on the repository have changed, their properties will be overwritten by those in the XML file.

For more information about object ownership, see "About Object Ownership in DAC".

Exporting and Applying Patches Using the Command Line

You can use a command line to export patches and apply patches to the DAC repository. The command line parameters are exposed in the AutomationUtils.bat file, which is located in the <Domain_Home>\dac directory. For information about how to use the parameters, see "DAC Repository Command Line Parameters".