18 Using Version Control (Legacy Mode)

This chapter describes how to work with version management in Oracle Data Integrator.

Note:

This chapter is applicable only for the legacy mode of versioning in ODI. If you want to enable VCS for Subversion, then none of the description from this chapter is applicable and you must refer to "Integrating ODI with Version Control Systems".

Oracle Data Integrator provides a comprehensive system for managing and safeguarding changes. The version management system allows flags on developed objects (such as projects, models, etc) to be automatically set, to indicate their status, such as new or modified. It also allows these objects to be backed up as stable checkpoints, and later restored from these checkpoints. These checkpoints are created for individual objects in the form of versions, and for consistent groups of objects in the form of labels.

Note:

Version management is supported for master repositories installed on database engines such as Oracle, Hypersonic SQL, and Microsoft SQL Server. For a complete list of certified database engines supporting version management refer to the Platform Certifications document on OTN at: http://www.oracle.com/technology/products/oracle-data-integrator/index.html.

This chapter includes the following sections:

Working with Object Flags

When an object is created or modified in Designer Navigator, a flag is displayed in the tree on the object icon to indicate its status. Table 18-1 lists these flags.

Table 18-1 Object Flags

Flag Description

inserted icon

Object status is inserted.

updated icon

Object status is updated.

When an object is inserted, updated or deleted, its parent objects are recursively flagged as updated. For example, when a step is inserted into a package, it is flagged as inserted, and the package, folder(s) and project containing this step are flagged as updated.

When an object version is checked in (refer to "Working with Versions" for more information), the flags on this object are reset.

Working with Versions

A version is a backup copy of an object. It is checked in at a given time and may be restored later. Versions are saved in the master repository. They are displayed in the Version tab of the object window.

The following objects can be checked in as versions:

  • Projects, Folders

  • Packages, Scenarios

  • Mappings (including Resuable Mappings), Procedures, Knowledge Modules

  • Sequences, User Functions, Variables

  • Models, Model Folders

  • Labels

  • Load Plans

Checking in a version

To check in a version:

  1. Select the object for which you want to check in a version.

  2. In the property inspector, select the Version tab. In the Versions table, click the Create a new version button (a green plus-sign icon). Alternatively, right-click the object and select Version, and then Create Version, from the context menu.

  3. In the Versioning dialog, review Previous Versions to see the list of versions already checked in.

  4. A version number is automatically generated in the Version field. Modify this version number if necessary.

  5. Enter the details for this version in the Description field.

  6. Click OK.

When a version is checked in, the flags for the object are reset.

Displaying previous versions of an object

To display previous versions of an object:

When editing the object, the Version tab provides creation and update information, the internal and global IDs for this object, and a list of versions checked in, with the check in date and the name of the user who performed the check in operation.

Restoring a version from the Version tab

Note:

You can also restore a version from the Version Browser. See: "Restoring a version with the Version Browser".

WARNING:

Restoring a version cannot be undone. It permanently erases the current object and replaces it by the selected version. Consider creating a new version of your current object before restoring a version.

To restore a version from the Version tab:

  1. Select the object for which you want to restore a version.

  2. In the property inspector, select the Version tab. Alternatively, right-click the object and select Version, and then Restore..., from the context menu.

    In the Versions table, select the row corresponding to the version you want to restore. Click the Restore a version button, or right-click the row and select Restore from the context menu.

  3. Click Yes to confirm the restore operation.

Browsing versions

To browse versions:

Oracle Data Integrator contains a tool, the Version Browser, which is used to display the versions stored in the repository.

  1. From the main menu, select ODI > Version Browser...

  2. Use the Object Type and Object Name drop down lists to filter the objects for which you want to display the list of versions.

From the Version Browser, you can compare two versions, restore a version, export a version as an XML file or delete an existing version.

Note:

The Version Browser displays the versions that existed when you opened it. Click Refresh to view all new versions created since then.

Comparing two versions with the Version Browser

To compare two versions with the Version Browser, see "Working with the Version Comparison Tool".

Deleting a version with the Version Browser

To delete a version with the Version Browser:

  1. Open the Version Browser.

  2. Select the version you want to delete.

  3. Click the Delete icon in the version table (a red X button), or right-click and select Delete from the context menu.

The version is deleted.

Restoring a version with the Version Browser

WARNING:

Restoring a version cannot be undone. It permanently erases the current object and replaces it by the selected version. Consider creating a new version of your current object before restoring a version.

To restore a version with the Version Browser:

  1. Open the Version Browser.

  2. Select the version you want to restore.

  3. Click the Restore this version button, or right-click and select Restore from the context menu.

  4. Click OK to confirm the restore operation.

The version is restored in the repository.

Exporting a version with the Version Browser

To export a version with the Version Browser:

This operation exports the version to a file without restoring it. This exported version can be imported into another repository.

Note:

Exporting a version exports the object contained in the version and not the version information. This allows you to export an old version without having to actually restore it in the repository.

  1. Open the Version Browser.

  2. Select the version you want to export.

  3. Click the Export this version as an XML file button, or right-click and select Export from the context menu.

  4. Select the Export Directory and specify the Export Name. Select Replace existing files without warning to overwrite files of the same name in the export directory without confirmation.

  5. Click OK.

The version is exported to the given location.

Working with the Version Comparison Tool

Oracle Data Integrator provides a comprehensive version comparison tool. This graphical tool is to view and compare two different versions of an object.

The version comparison tool provides the following features:

  • Color-coded side-by-side display of comparison results: The comparison results are displayed in two panes, side-by-side, and the differences between the two compared versions are color coded.

  • Comparison results organized in tree: The tree of the comparison tool displays the comparison results in a hierarchical list of node objects in which expanding and collapsing the nodes is synchronized.

  • Report creation and printing in PDF format: The version comparison tool is able to generate and print a PDF report listing the differences between two particular versions of an object.

  • Supported objects: The version comparison tool supports the following objects: Project, Folder, Package, Scenario, Mapping, Procedure, Knowledge Module, Sequence, User Function, Variable, Model, Model folder, and Label.

  • Difference viewer functionality: This version comparison tool is a difference viewer and is provided only for consultation purposes. Editing or merging object versions is not supported. If you want to edit the object or merge the changes between two versions, you have to make the changes manually directly in the concerned objects.

Viewing the Differences between two Versions

To view the differences between two particular versions of an object, open the Version Comparison tool.

There are three different way of opening the version comparison tool:

By selecting the object in the Projects tree

  1. From the Projects tree in Designer Navigator, select the object whose versions you want to compare.

  2. Right-click the object.

  3. Select Version > Compare with version...

  4. In the Compare with version editor, select the version with which you want to compare the current version of the object.

  5. Click OK.

  6. The Version Comparison tool opens.

Using the Versions tab of the object

  1. In Designer Navigator, open the object editor of the object whose versions you want to compare.

  2. Go to the Version tab.

    The Version tab provides the list of all versions created for this object. This list also indicates the creation date, the name of the user who created the version, and a description (if specified).

  3. Select the two versions you want to compare by keeping the <CTRL> key pressed.

  4. Right-click and select Compare...

  5. The Version Comparison tool opens.

Using the Version Browser

  1. Open the Version Browser.

  2. Select two versions that you want to compare, by using control-left click to multi-select two different rows. You must select rows that correspond to the exact same object.

  3. Click the Compare two versions for identical objects icon in the version table, or right-click and select Compare from the context menu.

  4. The Version Comparison tool opens.

  5. To print a copy of the object comparison, click Print. See: "Generating and Printing a Report of your Comparison Results".

    Click Close when you are done reviewing the comparison.

The Version Comparison tool shows the differences between two versions: on the left pane the newer version and on the right pane the older version of your selected object.

The differences are color highlighted. The following color code is applied:

Color Description
White (default) unchanged
Red deleted
Green added/new
Yellow object modified
Orange field modified (the value inside of this fields has changed)

Note:

If one object does not exist in one of the versions (for example, when it has been deleted), it is represented as an empty object (with empty values).

Using Comparison Filters

Once the version of an object is created, the Version Comparison tool can be used at different points in time.

Creating or checking in a version is covered in"Working with Versions".

The Version Comparison tool provides two different types of filters for customizing the comparison results:

  • Object filters: By selecting the corresponding check boxes (New and/or Deleted and/or Modified and/or Unchanged) you can decide whether you want only newly added and/or deleted and/or modified and/or unchanged objects to be displayed.

  • Field filters: By selecting the corresponding check boxes (New and/or Deleted and/or Modified and/or Unchanged) you can decide whether you want newly added fields and/or deleted fields and/or modified fields and/or unchanged fields to be displayed.

Generating and Printing a Report of your Comparison Results

To generate a report of your comparison results in Designer Navigator:

  1. In the Version Comparison tool, click Print.

  2. In the Report Generation dialog, set the Filters on objects and Filters on fields according to your needs.

  3. In the PDF file location field, specify a file name to write the report to. If no path is specified, the file will be written to the default directory for PDF files. This is a user preference.

  4. Check the box next to Open file after generation if you want to view the generated report in a PDF viewer.

    Note:

    In order to view the generated report, you must specify the location of Adobe Acrobat Reader in the user parameters. You can also set the default PDF generation directory. To set these values, select the Preferences... option from the Tools menu. Expand the ODI node, and then the System node, and select Reports. Enter (or search for) the location of your preferred PDF Viewer, and of your Default PDF generation directory.

  5. Click Generate.

A report in Adobe PDF format is written to the file specified in step 0

Working with Labels

A label is a comprehensive and consistent set of interdependent versions of objects. Like other objects, it can be checked in at a given time as a version, and may be restored at a later date. Labels are saved into the master repository. A label assembles a group of versions called the label's elements.

A label is automatically assembled using cross-references. By scanning cross-references, a label automatically includes all dependent objects required for a particular object. For example, when adding a project to a label, versions for all the models used in this project's interfaces are automatically checked in and added to the label. You can also manually add or remove elements into and from the label.

Labels are displayed in the Labels accordion in Designer Navigator and in Operator Navigator.

The following objects may be added into labels:

  • Projects

  • Models, Model Folders

  • Scenarios

  • Load Plans

  • Global Variables, Knowledge Modules, User Functions and Sequences.

To create a label:

  1. In Designer Navigator or Operator Navigator, from the Labels toolbar menu select New Label.

  2. In the Labels editor, enter the Name of your label and a Description.

  3. From the File menu select Save.

The resulting label is an empty shell into which elements may then be added.

Working with Elements in a Label

This section details the different actions that can be performed when working with elements of a label.

Adding Elements

To add an element, drag the object from the tree into the Elements list in the label editor. Oracle Data Integrator scans the cross-references and adds any Required Elements needed for this element to work correctly. If the objects being added have been inserted or updated since their last checked in version, you will be prompted to create new versions for these objects.

Removing Elements

To remove an element from a label, select the element you want to remove in the Elements list and then click the Delete button. This element disappears from the list. Existing checked in versions of the object are not affected.

Rolling Back Objects

To roll an object back to a version stored in the label, select the elements you want to restore and then click the Restore button. The elements selected are all restored from the label's versions.

Synchronizing Labels

Synchronizing a label automatically adds required elements that have not yet been included in the label, creates new versions of modified elements and automatically removes unnecessary elements. The synchronization process brings the content of the label up to date with the elements (projects, models, etc) stored in the repository.

To synchronize a label:

  1. Open the label you want to synchronize.

  2. Click Synchronize in the toolbar menu of the Elements section.

  3. Oracle Data Integrator scans the cross-references. If the cross-reference indicates that the label is up to date, then a message appears. Otherwise, a list of elements to add or remove from the label is shown. These elements are grouped into Principal Elements (added manually), Required Elements (directly or indirectly referenced by the principal elements) and Unused Elements (no longer referenced by the principal elements).

  4. Check the Accept boxes to version and include the required elements or delete the unused ones.

  5. Click OK to synchronize the label. Version creation windows may appear for elements requiring a new version to be created.

You should synchronize your labels regularly to keep the label contents up-to-date. You should also do it before checking in a label version.

Restoring and Checking in a Label

The procedure for checking in and restoring a label version is similar to the method used for single elements. See "Working with Versions" for more details.

You can also restore a label to import scenarios into production in Operator Navigator or Designer Navigator.

To restore a scenario from a label:

  1. Double-click a label to open the Label editor.

  2. Select a scenario from the Principal or Required Elements section. Note that other elements, such as projects and mappings, cannot be restored.

  3. Click Restore in the toolbar menu of the Elements section.

The scenario is now accessible in the Scenarios tab.

Note that you can also use the Version Browser to restore scenarios. See "Restoring a version with the Version Browser".

Note:

When restoring a label, elements in the label are not automatically restored. They must be restored manually from the Label editor.

Importing and Exporting Labels

Labels can be exported and imported similarly to other objects in Oracle Data Integrator. Export/Import is used to transfer labels from one master repository to another. Refer to Chapter 22, "Exporting and Importing," for more information.