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 allows you to move subsets of data from one environment to another. For example, when issues are fixed in a development environment, you can move the updated metadata to QA or production environments.

You can also add identifiers for deleted objects to a patch; DAC will attempt to find these objects and remove them from the target repository when the patch is applied.

The DAC metadata patch feature can be used with custom source system containers only and not with predefined ("out-of-the-box") containers.

This chapter contains the following topics:

• 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 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. 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. 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 information about what objects you can add to a patch, see "About Patch Contents".

  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 updated with the patch contents stored in the XML file. Any objects contained in the patch will be applied to the target repository. If the patch contains identifiers for deleted objects, DAC will attempt to find these objects and remove them from the target repository when the patch is applied.

  After the patch process, the patch status will be one of the following:

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

  • Incomplete. The process of applying the patch completed with one or more errors.

  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

• About Patch Contents

• 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

You can create a patch in the following ways:

• Use the Working Patches tab to create a new, empty patch.

• Create a new patch at the time you add the first contents

  After you create the patch, you then add contents to it. See "About Patch Contents" for information about which objects can be added to a patch, and "Adding Contents to a Patch" for instructions on adding patch contents.

To create a new patch in the Working Patches tab:

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.

To create a new patch at the time you add the first contents

1. In the Design view, select the appropriate tab that contains the contents you want to add to the patch.

2. Query for and select the object you want to add to the patch.

3. Right-click the object, and select Add Object 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, do the following:

   1. Click Create a New Patch.

   2. Enter a descriptive name for the patch.

   3. Click OK.

   The new patch will appear in the Working Patches tab. DAC automatically sets the status as Open and the Patch Version as 1.

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 to have only the the immediate child objects added or the children of the child objects as well. Table 12-1 lists the parent objects you can add to a patch and the immediate child objects that will be added. Also, when you add a child object to a patch, the parent object is automatically included.

  When you add a container-dependent object to a patch, you have the option to define a timestamp range that acts as a filter so that only the child objects that are new or changed during the time period you specify will be added to the patch.

  You can also add to the patch unique identifiers for deleted objects, which will then delete the objects from the target repository when the patch is applied. You add identifiers for deleted objects to the patch by specifying a time range in the Edit subtab of the Working Patches tab in the Setup view.

  Table 12-1 Objects and Immediate Child Objects Added to Patches

  Parent Object Added to Patch	Immediate Child Objects Also Added to Patch
  Subject area	Configuration tags Tables Tasks Note: You need to reassemble the subject area after the patch has been applied to the target repository.
  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

  
  

• Execution plans

  When you add an execution plan to a patch, only the execution plan parent object is listed in the Contents subtab of the Working Patches and Applied Patches tabs. However, the following child objects will be exported to the patch XML file even though they do not appear in the Contents subtab:

  • Connectivity Parameters

  • Tables

  • Concurrent Dependencies

  • Preceding Tasks

  • Following Tasks

  • Ordered Tasks

  • Subject Areas

  • Immediate Dependencies

    Note: The data under the All Dependencies subtab is not exported to the patch XML file. The data under the All Dependencies subtab can be computed in the target repository by selecting the All Dependencies subtab, and then clicking Go in the subtab toolbar. After the query results appear, click Generate.

  Note the following points:

  • If the execution plan contains one or more execution instances, you must manually add the instances to the patch. The execution instances are not automatically included in the patch when you add the parent execution plan. If you do not manually add the execution instances, they will not be present in the target repository.

  • If an execution plan contains tasks or subject areas from source system containers that are not in the DAC repository, then the execution plan will not be applied in the target repository.

    For example, if an execution plan has subject areas and tasks from container 1 and container 2 but the target DAC repository only contains metadata for container 3, the execution plan will not be applied to the target DAC repository.

• 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

  From the Working Patches tab in the Setup view, you can:

  • Add a patch to another 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).

  • Add objects to a patch based on a timestamp range and a distinct set of containers. Only objects that are new or changed during a timestamp range you specify and that reside within one or more containers that you specify will be added to the patch.

Adding Contents to a Patch

You can select any of the objects listed in the section "About Patch Contents" to be included in a patch.

Follow one of the procedures below to add to an object to a patch:

• To add container-specific contents to a patch

• To add an execution plan to a patch

• To add a seed data object to a patch

• To add a patch as a child patch to another patch

• To add contents to a patch based on a timestamp range and distinct containers

After you have added contents to a patch, you can verify the results by following the steps in "To view the contents of a patch".

To add container-specific contents to a patch

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. Select the appropriate source system container from the drop-down list.

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

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

6. 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.

7. In the Patches dialog, do one of the following:

   - Add the object to an existing patch by selecting Select a patch, and then clicking in the field below to open a dialog from which you can select the appropriate patch.

   - Create a new patch to which the object will be added by selecting Create a new patch, and entering a descriptive name for the patch in the text field.

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

   - Selected parent object(s) and immediate child object(s)

   An immediate child object is the object represented by the object subtab in the DAC user interface. For example, if you select a subject area, its immediate child objects are task links, table links, and configuration tag links.

   - Selected parent object(s) and all child object(s)

   When you select to have all child objects added to a patch, then the children of the child objects are also added. For example, a subject area is a parent object. The tasks, tables and configuration tag links are its immediate child objects. Actual tasks, tables and configuration tags are pulled into the patch because of the links. The child objects have child objects of their own. For example, a table child object has columns as its child objects.

   Note: If you added a subject area to a patch, you need to reassemble the subject area after the patch has been applied to the target repository. In general, you need to reassemble subject areas if there are changes to the applicable tasks.

9. (Optional) In the Select Time Stamps area, specify a timestamp range to act as a filter to so that only the child objects that are new or changed during the time period you specify will be added to the patch:

   - Click in the From Timestamp field to open the Date dialog, and configure the beginning timestamp.

   - Click in the To Timestamp field to open the Date dialog, and configure the ending timestamp.

10. (Optional) Add unique identifiers for deleted objects (in the source repository) that you want to delete in the target repository:

    1. Go to the Edit subtab in the Working Patches tab.

    2. Specify the time range for which you want to collect deleted objects by clicking in the Deleted From and Deleted To fields and selecting a date and time.

    3. Click Save.

To add an execution plan to a patch

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. In the Execute view, go to the Execution Plans tab.

4. Query for the execution plan you want to add to the patch.

5. Right-click the execution plan, and then select Add Object(s) to Patch.

6. 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.

7. In the Patches dialog, do one of the following:

   - Add the object to an existing patch by selecting Select a patch, and then clicking in the field below to open a dialog from which you can select the appropriate patch.

   - Create a new patch to which the object will be added by selecting Create a new patch, and entering a descriptive name for the patch in the text field.

   Note:

   If the execution plan contains one or more execution instances, you must manually add the instances to the patch. The execution instances are not automatically included in the patch when you add the parent execution plan. If you do not manually add the execution instances, they will not be present in the target repository.

To add a seed data object to a patch

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. On the Tools menu, select Seed Data, and then select the appropriate menu item.

4. In the dialog that opens, right-click the object you want to add to the patch, and then select Add Object(s) to Patch.

5. 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.

6. In the Patches dialog, do one of the following:

   - Add the object to an existing patch by selecting Select a patch, and then clicking in the field below to open a dialog from which you can select the appropriate patch.

   - Create a new patch to which the object will be added by selecting Create a new patch, and entering a descriptive name for the patch in the text field.

To add a patch as a child patch to another patch

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. In the Working Patches tab of the DAC Setup view, select the patch that you want to add to another patch.

4. Right-click, select Patches, and then select Add as Child Patch(es).

5. Do one of the following:

   • Add the object to an existing patch by selecting Select a patch, and then clicking in the field below to open a dialog from which you can select the appropriate patch.

   • Create a new patch to which the object will be added by selecting Create a new patch, and entering a descriptive name for the patch in the text field.

To add contents to a patch based on a timestamp range and distinct containers

Follow this procedure to add objects to a patch based on a timestamp range and a distinct set of containers. Only objects that are new or changed during a timestamp range you specify and that reside within one or more containers that you specify will be added to the patch.

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. In the Working Patches tab of the DAC Setup view, select the patch to which you want to add contents.

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

   The Patching... dialog opens.

5. Set up a timestamp range so that only objects that are new or changed during this time period are added to the patch:

   1. Click in the From Timestamp field to open the Date dialog, and configure the beginning timestamp.

   2. Click in the To Timestamp field to open the Date dialog, and configure the ending timestamp.

6. Select one or more containers that hold the objects you want to add to the patch.

7. Click OK.

To view the contents of a 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.

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".

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

5. On the target repository, reassemble all custom subject areas that contain the patch contents.

   For instructions on assembling a subject area, see "Creating a Subject Area".

6. On the target repository, rebuild all custom execution plans that contain the patch contents.

   For instructions on rebuilding execution plans, see "Building and Running Execution Plans".

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 utilities 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 Utilities".