17 Organizing and Documenting your Work

This chapter describes how to organize and document your work in Oracle Data Integrator.

This chapter includes the following sections:

• Section 17.1, "Organizing Projects with Folders"

• Section 17.2, "Organizing Models with Folders"

• Section 17.3, "Using Cross-References"

• Section 17.4, "Using Markers and Memos"

• Section 17.5, "Handling Concurrent Changes"

• Section 17.6, "Creating PDF Reports"

17.1 Organizing Projects with Folders

Before you begin creating an integration project with Oracle Data Integrator, it is recommended to think about how the project will be organized.

Rearranging your project afterwards may be dangerous. You might have to redo all the links and cross-references manually to reflect new locations.

Within a project, interfaces, procedures and packages are organized into folders and sub-folders. It is recommended to maintain your project well organized by grouping related project components into folders and sub-folders according to criteria specific to the project. Folders simplify finding objects developed in the project and facilitate the maintenance tasks. Sub-folders can be created to an unlimited number of levels.

Note that you can also use markers to organize your projects. Refer to Section 17.4, "Using Markers and Memos" for more information.

17.1.1 Creating a New Folder

To create a new folder:

1. In Designer Navigator expand the Projects accordion.

2. Select the project into which you want to add a folder.

3. Right-click and select New Folder.

4. In the Name field, enter a name for your folder.

5. Select Save from the File main menu.

The empty folder appears.

To create a sub-folder:

1. Create a new folder as described in Section 17.1.1, "Creating a New Folder".

2. Drag and drop the new folder into the parent folder.

17.1.2 Arranging Project Folders

To arrange your project folders in the project hierarchy, drag and drop a folder into other folders or on the Project. Note that it is not possible to move a folder from one Project to another Project.

17.2 Organizing Models with Folders

A model folder groups related models according to criteria specific to the project. A model folder may also contain other model folders. Sub-folders can be created to an unlimited number of levels.

Note that you can also use markers to organize your models. Refer to Section 17.4, "Using Markers and Memos" for more information.

17.2.1 Creating a New Model Folder

To create a model folder:

1. In Designer Navigator expand the Models accordion.

2. Click New Model Folder in the toolbar of the Models accordion.

3. In the Name field, enter a name for your folder.

4. Select Save from the File main menu.

The empty model folder appears.

17.2.2 Arranging Model Folders

To move a model into a folder:

1. In Designer Navigator expand the Models accordion.

2. Select the model, then drag and drop it on the icon of the destination model folder.

The model moves from its current location to the selected model folder.

Note the following when arranging model folders:

• A model can only be in one folder at a time.

• Model folders can be also moved into other model folders.

17.2.3 Creating and Organizing Sub-Models

A sub-model is an object that allows you to organize and classify the datastores of a model in a hierarchical structure. The root of the structure is the model. A sub-model groups functionally homogeneous datastores within a model. The datastores of a model can be inserted into a sub-model using drag and drop, or by automatic distribution.

The classification is performed:

• During the reverse-engineering process, the RKM may create sub-models and automatically distribute datastores into these sub-models. For example RKM handling large data models from ERP systems use this method.

• Manually, by drag and dropping existing datastores into the sub-models.

• Automatically, using the distribution based on the datastore's name.

To create a sub-model:

1. In Designer Navigator expand the Models accordion.

2. In the Models accordion, select the model or the sub-model into which you want to add a sub-model.

3. Right-click and select New Sub-Model.

4. On the Definition tab, enter a name for your sub-model in the Name field.

5. Click OK.

The new sub-model is created with no datastore.

Arranging Sub-Models

To manually file a datastore into a sub-model:

1. In Designer Navigator expand the Models accordion.

2. In the Models accordion, select the datastore you wan to move into the sub-folder.

3. Drag and drop it into the sub-model.

The datastore disappears from the model and appears in the sub-model.

Setting-up Automatic Distribution

Distribution allows you to define an automatic distribution of the datastores in your sub-models.

Datastores names are compared to the automatic assignment mask. If they match this pattern, then they are moved into this sub-model. This operation can be performed manually or automatically depending on the Datastore Distribution Rule.

There are two methods to classify:

• By clicking Distribution in the Distribution tab of a sub-model, the current rule is applied to the datastores.

• At the end of a reverse-engineering process, all sub-model rules are applied, the order defined by the Order of mask application after a Reverse Engineer values for all sub-models.

To set up the automatic distribution of the datastores in a sub-model:

1. In the sub-model's Distribution tab, select the Datastore distribution rule:

   The Datastore Distribution rule determines which datastores will be taken into account and compared to the automatic assignment mask:

   • No automatic distribution: No datastore is taken in account. Distribution must be made manually.

   • Automatic Distribution of all Datastores not already in a Sub-Model: Datastores located in the root model in the sub-model tree are taken in account.

   • Automatic Distribution of all Datastores: All datastores in the model (and sub-models) are taken in account.

2. In the Automatic Assignment Mask field, enter the pattern the datastore names must match to be classified into this sub-model.

3. In the Order of mask application after a Reverse Engineer field, enter the order in which all rules should be applied at the end of a reverse. Consequently, a rule with a high order on all datastores will have precedence. A rule with a high order on non-classified datastores will apply only to datastores ignored by the other rules' patterns. At the end of the reverse, new datastores are considered non classified. Those already classified in a sub-model stay attached to their sub-model.

4. Click Distribution. The current rule is applied to the datastores.

17.3 Using Cross-References

Objects in Oracle Data Integrator (datastores, models, interfaces, etc) are interlinked by relationships varying from simple usage associations (an integration interface uses Knowledge Modules) to complex ones such as code-interpretation relationships (a variable is used in the mappings or filters of an interface). These relationships are implemented as cross-references. They are used to check/maintain consistency between related objects within a work repository. Cross-references, for example, prevent you from deleting an object if it is currently referenced elsewhere in the work repository.

Not all relationships appear as cross-references:

• Relationships with objects from the master repository (For example, a data model is related to a technology) are not implemented as cross-references, but as loose references based on object codes (context code, technology code, datatype code, etc). Modifications to these codes may cause inconsistency in the references.

• Strong relationships in the work repository (a folder belongs to a project) are enforced in the graphical user interface and within the repository (in the host database as foreign keys). These relationships may not normally be broken.

17.3.1 Browsing Cross-References

When modifying an object, it is necessary to analyze the impact of these changes on other developments. For example, if the length of a column is altered, the integration interfaces using this column as a source or a target may require modification. Cross-references enable you to immediately identify the objects referenced or referencing a given object, and in this way provide effective impact analysis.

Cross-references may be browsed in Designer Navigator as described in Table 17-1.

Table 17-1 Cross-References in Designer Navigator

Accordion	Icon	Description
Projects and Other accordion		The Used in and Used by nodes appear under an object node. The Used in node lists the objects from which the current object is referenced. In the case of a variable, for example, the packages containing steps referencing this variable and the interfaces using this variable in the mappings, filters, etc. will be displayed. The Used by node lists the objects that are using the current object.
Models accordion		The Used in node appears under an object node and lists the objects referencing the current datastore, model or sub-model as a source or a target of an interface, or in package steps.
Models accordion		The Used to Populate and Populated By nodes display the datastores used to populate, or populated by, the current datastore

These cross-referenced nodes can be expanded. The referencing or referenced objects can be displayed or edited from the cross-reference node.

17.3.2 Resolving Missing References

When performing version restoration operations, it may happen that an object in the work repository references nonexistent objects. A typical situation for this is when restoring an old version of a project without restoring all the associated models used in its integration interfaces.

Such a situation causes Missing References errors messages in Oracle Data Integrator when opening the objects (for example, the interfaces) which reference nonexistent objects. An object with missing cross-references is marked in the tree with the missing reference marker and its parent objects are flagged with a warning icon.

To display the details of the missing references for an object:

1. In Designer Navigator, double-click the object with the missing reference marker.

2. The object editor opens. In the object editor, select the Missing References tab.

3. The list of referenced objects missing for the cross-references is displayed in this tab.

To resolve missing references:

Missing cross-reference may be resolved in two ways:

• By importing/restoring the missing referenced object. See Chapter 18, "Working with Version Management"and Chapter 19, "Exporting/Importing" for more information.

• By modifying the referencing object in order to remove the reference to the missing object (for example, remove the Refresh Variable step referencing the nonexistent variable from a package, and replace it with another variable).

Note:

If a text (such as an interface mapping/join/filter, a procedure command, and so forth) contains one or more missing references, the first change applied to this text is considered without any further check. This is because all the missing references are removed when the text is changed and the cross-references computed, even if some parts of the text are still referring to an object that doesn't exist.

17.4 Using Markers and Memos

Almost all project and model elements may have descriptive markers and memos attached to them to reflect your project's methodology or help with development.

17.4.1 Markers

Flags are defined using markers. These markers are organized into groups, and can be applied to most objects in a project or a models.

Typical marker groups are:

• The development cycle (development, test, production)

• Priorities (low, medium, urgent, critical)

• Progress (10%, 20%, etc)

Global and Project Markers

Markers are defined in a project or in the Other view (Global Markers). The project markers can be used only on objects of the project, and global markers can be used in all models of the repository.

Flagging Objects

To flag an object with an icon marker:

1. In Designer Navigator, select an object in the Projects or Models accordion.

2. Right-click and select Add Marker, then select the marker group and the marker you want to set.

The marker icon appears in the tree. The marked object also appears under the marker's node. You can thus see all objects having a certain marker.

If you click in the tree an icon marker belonging to an auto-incremented marker group, you switch the marker to the next one in the marker group, and the icon changes accordingly.

Note:

Markers will not appear if the option Show Markers and Memo Flags is not checked. See Hiding Markers and Memos for more information.

To flag an object with string, numeric and date markers:

1. In Designer Navigator, double-click the object in the Projects or Models accordion.

2. In the object editor, select the Markers tab.

3. Click Insert a Marker.

4. In the new line, select the Group and Marker. You may also set the Value.

If the marker has an associated icon, it appears in the tree.

Filtering Using Markers

Markers can be used for informational purposes (for example, to have a global view of a project progress and resources). They can also be used when automating scenario generation by filter the packages. See Section 13.4, "Generating a Group of Scenarios" for more information.

The list of all objects using a certain marker is shown below the marker's node.

Customizing Markers

A new project is created with default markers. It is possible to customize the markers for a specific project as well as the global markers.

To define a marker group:

1. In Designer Navigator, click the Markers node in the Project accordion, or the Global Markers node in the Others accordion.

2. Right-click and select New Marker Group.

3. In the Group Name field, enter the name for the marker group, then define its Display Properties and Attributes.

4. Click Insert a new Marker to create a new marker in the group.

5. Select the marker Icon. If a marker stores date or a number, the icon should be set to <none>.

6. Select the marker Name, Type and other options.

7. Repeat operations 4 to 6 to add more markers to the group.

8. Select Save from the File main menu.

17.4.2 Memos

A memo is an unlimited amount of text attached to virtually any object, visible on its Memo tab. When an object has a memo attached, the memo icon appears next to it.

To edit an object's memo:

1. Right-click the object.

2. Select Edit Memo.

3. The Object editor opens, and the Memo tab is selected.

Hiding Markers and Memos

You can temporarily hide all markers and memo flags from the tree views, to improve readability.

To hide all markers and memo flags:

Deselect the Display Markers and Memo Flags option in the Designer Navigator toolbar menu. This preference is stored on a per-machine basis.

17.5 Handling Concurrent Changes

Several users can work simultaneously in the same Oracle Data Integrator project or model. As they may be all connected to the same repository, the changes they perform are considered as concurrent.

Oracle Data Integrator provides two methods for handling these concurrent changes: Concurrent Editing Check and Object Locking. This two methods can be used simultaneously or separately.

17.5.1 Concurrent Editing Check

The user parameter, Check for concurrent editing, can be set to 1 to perform to prevent you from erasing the work performed by another user on the object you try to save. Refer to Appendix B, "User Parameters" for more information.

If this parameter is set to 1, when saving changes to any object, Oracle Data Integrator checks whether other changes have been made to the same object by another user since you opened it. If another user has made changes, the object cannot be saved, and you must cancel your changes.

17.5.2 Object Locking

The object locking mechanism can be activated in Oracle Data Integrator automatically, when closing the Oracle Data Integrator or manually.

Automatic Object Locking

This mechanism is automatically activated. When an object is opened in a user interface, a popup window appears to ask if you want to lock the object. As long as an object is locked, only the user owning the lock can perform modifying the object, such as editing or deleting. Other operations, such as executing, can be performed by other users, but with a warning.

An object locked by you appears with a yellow lock icon. An object locked by another user appears with a red lock icon.

When the edition window is closed, a popup window appears to ask if you want to unlock the object.

Note that these windows are configured by the Lock object when opening and Unlock object when closing user parameters. See Appendix B, "User Parameters" for more information.

Releasing locks when closing the user interface

When closing Oracle Data Integrator, a window appears asking to unlock or save objects that you have locked or kept opened.

You can keep objects locked even if you are not connected to Oracle Data Integrator. This allows you to prevent other users from editing them in the meanwhile.

Managing manually locks

You can also manually manage locks on objects.

To manually lock an object:

1. Select the object in the tree.

2. Right-click, then select Locks > Lock.

A lock icon appears after the object in the tree.

To manually unlock an object:

1. Select the object in the tree

2. Right-click, then select Locks > Unlock.

The lock icon disappears in the tree.

To manage all locks:

1. Select Locked objects from the ODI menu.

2. The Locked Objects editor appears displaying all locked objects that you can unlock.

Note:

A user with the Supervisor privilege can remove locks for all other users.

17.6 Creating PDF Reports

In Oracle Data Integrator you have the possibility to print and share several types of reports with the PDF generation feature:

• Topology reports of the physical architecture, the logical architecture, or the contexts

• Reports of the version comparison results.

• Reports of an ODI object

• Diagram reports

Note:

In order to view the generated reports, you must specify the location of Acrobat® Reader™ in the Appendix B, "User Parameters" before launching the PDF generation.

17.6.1 Generating a Topology Report

Oracle Data Integrator provides the possibility to generate Topology reports in PDF format of the physical architecture, the logical architecture or the contexts.

To generate a topology report:

1. From the Topology Navigator toolbar menu select Generate Report and then the type of report you wish to generate:

   • Physical Architecture

   • Logical Architecture

   • Contexts

2. In the Report generation editor, enter the output PDF file location for your PDF report. Note that if no PDF file location is specified, the report in Adobe™ PDF format is generated in your default directory for pdf generation specified in the user parameters. Refer to Appendix B, "User Parameters" for more information.

3. If you want to view the PDF report after generation, select the Open file after the generation? option.

4. Click Generate.

17.6.2 Generating a Report for the Version Comparison Results

You can create and print a report of your comparison results via the Version Comparison Tool. Refer to the Section 18.3.3, "Generating and Printing a Report of your Comparison Results" for more information.

17.6.3 Generating a Report for an Oracle Data Integrator Object

In Designer Navigator you can generate different types of reports depending on the type of object. Table 17-2 lists the different report types for ODI objects.

Table 17-2 Different report types for ODI objects

Object	Reports
Project	Knowledge Modules
Project Folder	Folder, Packages, Interfaces, Procedures
Model Folder	Model Folder
Model	Model
Sub-model	Sub-model

To generate a report in Designer Navigator:

1. In Designer Navigator, select the object for which you wish to generate a report.

2. Right-click and select Print >Print <object>.

3. In the Report generation editor, enter the output PDF file location for your PDF report. Note that if no PDF file location is specified, the report in Adobe™ PDF format is generated in your default directory for pdf generation specified in the user parameters. Refer to Appendix B, "User Parameters" for more information.

4. If you want to view the PDF report after generation, select the Open file after the generation? option.

5. Click Generate.

17.6.4 Generating a Diagram Report

You can generate a complete PDF report of your diagram. Refer to Section 6.2.5, "Printing a Diagram" for more information.