Oracle9i Designer Migration Guide Part 2. Migrating the repository |
Contents

# Chapter 1 Introduction

This second part provides different scenarios and related migration tools for the migration of structured data from previous Oracle Designer releases, and the migration of files either from a source control system (e.g. PVCS/VM, ClearCase) or the migration of files/folders directly from the file system. The different migration scenarios share the following common structure:

1. Preparation
2. Migration of structured data
3. Migration of files
4. Reorganization steps
5. Migration of users and access privileges
6. Synchronizing the file system and database

The preparation step basically involves the clean-up of your "original" elements and a fresh Oracle9i Designer installation. Preparation should be followed by migrating your structured elements via the migration wizard. You can then easily enter the versioned world by just checking in structured elements. By organizing the files migration after the migration of structured elements you are able to integrate your files with the structured elements - both types of elements will share the same root-container. The migration of both object types should be succeeded by reorganization steps that involve a simple implementation of a promotion model via a combination of workareas and configurations. The reorganized repository should then be made accessible to subordinate users. Guidelines were given for creating subordinate users and the distribution of the appropriate access rights on the previously mentioned objects. Finally a significant part of your repository content will ultimately populate your databases and file systems. You can implement the file system synchronization within each workarea via the folder mapping option and the database synchronization within each workarea via the DDL generator.

This second part is concluded with an example of a typical migration plan.

# Chapter 2 Prerequisites and installation notes

You must precede the migration of structured data and files by an installation of Oracle9i Designer on the client side and a fresh repository installation on the server side in an Oracle8i or Oracle9i database instance.

The client and repository software is installed during installation of Oracle9iDS. The Oracle9iDS Installation Guide contains recommendations for hardware on the client and server sides. Once installed, you have to configure the repository in accordance with the Oracle9i SCM Repository Installation Guide.

This chapter contains guidelines for how to prepare a fresh Oracle9i Designer installation for migration.

Consult Chapter 3 in Part 1 for guidelines about entering or staying away from the versioned world. If you want to enter the versioned world you can enable element level versioning via the "Enable Version Support" option in the Repository Administration Utility directly after the fresh repository installation. Note that you cannot disable the versioning support option once you have enabled versioning, other than by creating a fresh Oracle9i Designer repository.

## Verify the client side and server side installation

The verification of a fresh Oracle9i Designer installation involves both the client side and server side.

### Verification of the client side

All software is now installed by the Oracle9iDS installation process. There is no longer a custom installation option.

### Verification of the server side

There are two options available to verify the success of the Oracle9i Designer repository installation:

- Verification of the installation log files
- The "View objects" option in the Oracle9i Designer RAU

#### Verification of the installation log files

Verify the content of a fresh Oracle9i Designer installation log file, written to the ORACLE_HOME\repadm61\logs directory after the installation.

#### "View objects" in the RAU

While connected as the Oracle9i Designer repository owner, open the Oracle9i Designer Repository Administration Utility and launch the View Objects option to verify the server side installation. Sort the overview on the status property. A successful Oracle9i Designer installation may not display the following values for the status property of all objects:

- Disabled
- Missing
- Invalid

Obviously you could directly check if any of database objects of the Oracle9i Designer repository owner is "invalid" via the status property of the view "user_objects".

## Prepare the Oracle9i Designer repository for migration

You can "run" the Oracle9i Designer repository either in a 'non-versioned' mode or version enabled. Multiple scenarios and criteria for versioning versus non-versioning are described in Chapter 3 of Part I: Version enabling versus non-versioning.

Skip the following activity if you do not want to enter the versioned world.

You can enable versioning via the Oracle9i Designer Repository Administration Utility (connected as the Oracle9i Designer repository owner). Subsequently enable the versioning option from the options menu if you would like to enter the versioned world.

Note that you cannot disable the version option once you have enabled versioning, other than by re-creating a fresh Oracle9i Designer repository.

## Public or private synonyms

You can "run" the Oracle9i Designer repository either with public or with private synonyms. The enabling or disabling of private synonyms is available at the Repository Administration Utility, as depicted below.

The use of public synonyms is more productive - no more reconciles per user- and will occupy less space in the system tablespace. You do not need to create more than 1500 private synonyms per user. Note however that the use of public synonyms allows you to create only one Oracle9i Designer repository instance per database instance.

## Reevaluate the file registry settings

Skip this section if you are not planning to load files in the repository.

Files in the repository can be stored as:

CLOB - Character Large Objects - Text file

BLOB - Binary Large Objects - Binary file

BLOB - Compressed

BLOB - Uncompressed

A file will be stored as one of the above methods based on its extension. These extensions and the subsequent storage method are stored persistently in a repository table - i$sdd_file_registry - that can be manuplated via the utility menu option Edit File Registry. Through this menu option new file extensions can be added and/or existing entries can be altered as illustrated below:

You should reevalute these file registry settings before the bulk loading of files from your third party source control tool or file system to enforce a cost effective and efficient storage of files. You cannot alter the storage method for a specific file and its subsequent versions once the file is uploaded in the repository. Any changes will only have an effect on new files.

# Chapter 3 Migrate structured data

The fresh Oracle9i Designer installation should be followed by a migration of your structured elements. The following subjects for the migration of structured data are discussed:

- An overview of the example of Headstart structured data
- An overview of different migration strategies for structured data
- Preparation steps
- Other hints and tips based on migration best practices of structured data
- Migration to an Oracle9i Designer repository (if applicable)
- Migration steps starting from an Oracle Designer 6.0 repository
- Post migration steps for structured data
- Verification of the migrated structured data

A great part of the activities of migrating structured data is also applicable if you do not want to enter the versioned world. Any sections that are not applicable in a non-versioned repository will be announced in italic.

## Example of Headstart structured data

The different migration scenerarios will be clarified using an abstract of 'Headstart 5.0.5' structured components and files. It is assumed that the structured Headstart 5.0.5 components are captured in two (Oracle Designer 6.0) application systems: HSD and QMS respectively, as illustrated below:

## Migration strategies for structured data

There are two strategies for migrating the repository content to Oracle9i Designer:

- Migrate an entire repository content in a single operation
- Migrate a sub-selection of application systems within a specific Oracle Designer 6.0 repository

The first strategy loads and migrates all application systems into a fresh Oracle9i Designer repository.

The second strategy allows you to load and migrate one or more interrelated application systems. Non-selected interrelated application systems will stay behind in an Oracle Designer 6.0 repository. These application systems are candidates for migration at a later time.

Note that the Oracle9i Designer migration method has changed significantly. An Oracle Designer 6.0 repository will not be upgraded to an Oracle9i Designer repository during the migration.

The Oracle9i Designer repository content (or part of it) will be copied into a freshly installed (or already populated) Oracle9i Designer repository. Note also that the migration is only supported starting from an Oracle Designer 6.0 or Oracle Designer 2.1.2 repository - although it is highly recommended to update your Oracle Designer 2.1.2 to the latest patch level (patch 7 of an Oracle Designer 6.0 repository) before launching the migration wizard.

### Migrate an entire repository content

There are several migration scenarios available to bring your structured objects forward to Oracle9i Designer. This section will discuss a 'Big Bang' migration or the migration of an entire repository.

The 'Big Bang' migration approach is applicable in the following circumstances:

- The structured elements in the application systems are closely interrelated. You cannot isolate a subset of application systems because of its (many) interdependencies (also known as shares). In addition there are strong relationships between the files captured in the third party source control tool and the structured data in Oracle Designer.
- The redesign activities - directly started after the migration - are applicable to all application systems simultaneously.

### Migrate a sub-selection of application systems

You may want to adopt a staged migration scenario in the following circumstances:

- The Oracle9i Designer migration concerns a pilot or a test migration
- It may not be necessary to migrate all your application systems and all files in case of a pilot or an evaluation of your migration scenario.
- A coherent set of application systems will be migrated and subsequently redesigned in the Oracle9i Designer environment. At the same time other application systems within previous Oracle Designer repositories will or must stay behind.

> This migration approach may not need to be complex if you choose mutual independent sets of application systems for each migration. You can easily add new sets of application systems to your Oracle9i Designer repository as long as they are mutually exclusive. However if there is any overlap between your application systems your migration scenario will look like the following option. You should try to avoid staged migration of highly interdependent application systems.

- Support and therefore changes are needed on the "original" environment during the migration period of the structured elements and files. These interim changes must also be brought forward to Oracle9i Designer.

  This situation requires a second migration cycle - though on a smaller scale - specifically if you have to migrate a substantial number of applications. In this second migration cycle you have bring forward both changed structured elements and changed files from your "original" repositories to Oracle9i Designer. The migration for both types will be based upon an isolation of the changes in the "original" repositories and an isolation of the corresponding elements in Oracle9i Designer.

The necessary migration steps for the staged approach will be discussed later in this chapter. See "Post migration steps for structured elements within a staged migration approach".

## Preparing (cleaning up) your 'old' repository content

A clean-up of your old Oracle Designer repositories should precede the actual migration. It will not only save time during the migration but it will also limit future repository maintenance effort.

The following clean-up checklist is applicable to structured data:

- Remove obsolete users.
- Remove unused application systems. Candidate unused application systems are skeleton applications with no shares to 'actual' application systems or 'old' versioned application systems.
- Remove obsolete objects and unshare unused objects.
- Consider the removal of User Defined Sets. Although User Defined Sets are still available in Oracle9i Designer they will - by definition - not capture specific object versions. The object versions visible in a User Defined Set may change over time. You should use configurations instead if you want to capture specific object versions persistently like a change request.
- Reconnect your application systems that receive shares from 'obsolete' application systems to actual application systems. For example if HSD505 receives shares (e.g. preference sets) from QMS342, you could reconnect to for example QMS505 or higher by archiving HSD505 only and immediately restore HSD505 (as HSD505_copy) with the reconnect option to QMS505. Note that archiving the single application system HSD505 will result in a skeleton share from QMS342 and that the reconnect option - while restoring - allows you to reconnect the skeleton application to other application systems.
- Remove unused diagrams (e.g. old versions) and diagrams that can be fully derived from the repository content (e.g. Module diagrams).
- Consolidate all other diagrams. The visual diagram information is stored separately from the structured elements and their properties and may therefore not always be in sync. The consolidate option synchronizes the diagram information with the information of the structured elements and their properties. To consolidate a diagram in Release 2.x./6.0, open it and choose Edit > Consolidate > All.
- Remove any parent/child relationships between application systems. There is no such thing as a parent/child relationship in the context of Oracle9i Designer.

The application interdependencies - implemented by one or more shares between application systems - can be very complex. It may not be very obvious how application systems are mutually dependent. The Quickscan Analyzer utility of the Oracle Echo tool set is able to visualise the content and mutual dependencies between application systems via an Entity Relationship Diagram. The tool depicts a repository content (or a sub-selection of application systems) into a specific Quick Scan application system, an application system into an entity, object types instances into attributes and shares into relationships. An example of a quickscan ERD is given below:

## Other hints and tips based on migration best practices

Below you will find a comprehensive overview of migration best practices of structured data based on Oracle Designer migration - abstracted from Metalink between July 2000 and February 2001:

- Apply the appropriate most recent patch levels to the target and destination repositories. You can find these patches for Oracle Designer and Oracle Repository releases on Metalink.
- Apply the same database character sets in the target and destination database that host the repositories.
- Preferably start the migration as the repository owner. Although the migration is supported as a subordinate user, you need specific database access rights to successfully end the migration of one or more application systems (see also the Oracle9i SCM Repository Installation Guide). In addition there is the issue of application system ownership. The migration user will automatically become the application system owner. He or she then needs to transfer that ownership to another - administrative - user. Your user management and subsequent access rights can become extremely labor intensive if you introduce multiple application system owners.
- The migration should not be started from multiple workstations simultaneously. Once you start the migration wizard on one workstation do not attempt to start another migration session on another workstation until the first session is successfully completed.
- Verify that you have the same tnsnames.ora running on your source and destination database node. Your tnsnames.ora on your destination database node that hosts your Oracle9i Designer repository should be equal to your tnsnames.ora on your Oracle9i Designer workstation. The wizard itself will create a database link from the source Oracle Designer 6.0 repository to the target Oracle9i Designer repository. Note that the process that creates this database link is executed on the database server and not on your workstation - unless your source and destination database is running locally.
- No manipulation of data should take place during the migration in the target and source repositories.
- If you are still using Designer 2.1.x, migrate your repository first to Oracle Designer 6.0 and apply the latest Oracle Designer 6.0 patch level (Patch 7 was available in February 2002). There are several issues with migrating from a Designer 2.1.x repository that were solved once moved forward to Designer 6.0.
- Pilot a large volume set of application systems first. If you are planning to migrate a large volume of application systems in an existing populated repository you should pilot this type of migration in a shadow environment and examine the logging of the migration carefully if it does not complete successfully. As an alternative to a shadow environment you could also choose to restore a pre-migration database backup if the migration fails.
- If you migrate user-defined report data from an Oracle Designer 6.0 repository, note that user-defined reports, groups and parameters can be accessed only by a username that is identical to that of the user who created them.

Note that specific migration best practices for database elements, Oracle Developer components (e.g. Forms, Reports, Libraries and Menus) and WEB PL/SQL components are handled in parts 3, 4 and 5 of this migration guide respectively.

### Problems during migration

#### End of file on communication channel

Occasionally, the database connection is dropped during migration from a source repository on Oracle 8.0.4 or 8.0.5. The Oracle Error Number is 3113 and the message is 'End of file on communication channel'. This appears to be RDBMS related. The following suggestions may help to overcome the problem:

(a) Change the INIT.ORA parameter file for the source and target repository servers to increase the number of open cursors (OPEN_CURSORS) to 3000

(b) Upgrade the source repository to Oracle server 8.0.5.2.1.

Should you still experience this problem, please contact Oracle Support.

#### Unable to allocate an extent of %s blocks from tablespace %s

During migration from 2.x or 6.0 to 9i the following error may be reported:

> ORA-3232 unable to allocate an extent of %s blocks from tablespace %s

This is because a join of two tables required a sort operation that requested a temporary table segment. The size of the segment requested was larger than the next extent of the temporary tablespace from which it was requested.

There are two possible solutions. The next extent of the temporary tablespace cited in the error can be increased, or the request size can be reduced to fit within the next extent.

The preferred solution is to reduce the request size. To do this, examine the database INIT.ORA file (or query SYS.V$PARAMETER) to determine your database block size. Usually this will be a multiple of 2K bytes, such as 4096 or 8192. Then issue the SQL command:

> select next_extent/db_block_size from user_tablespaces where tablespace_name = 'tablespace_name';

where db_block_size is the appropriate value and tablespace_name is the name given in the original error message.

Take the value calculated and set the INIT.ORA parameter hash_multiblock_io_count to an equal or lesser value. Then restart the database and restart the migration.

## Migration steps from an Oracle Designer 1.3.2 repository to Oracle Designer 6.0 repository

You may skip this stage if you have already migrated to Oracle Designer 6.0.

The migration method for structured data is supported only if starting from an Oracle Designer 6.0 repository. You have to apply the following migration steps if your current release of Oracle Designer is 1.3.2.

### Load the user extensibility (if applicable)

Migrate via the Repository Administration Utility Upgrade tool or migrate via application system extracts.

### Unload Oracle Designer 1.3.2 user extensibility (optional)

Obviously you can skip this activity if you have not defined any user extensibility or if you do not want to bring forward the user extensibility into the Oracle9i Designer repository.

You first have to unload the Oracle Designer 1.3.2 user extensibility in order to keep your user extensibility. The unload option is available from the Oracle Designer 1.3.2 Repository Administration Utility.

### Load Oracle Designer 1.3.2 user extensibility into Oracle Designer 6.0 (optional)

If you want to bring forward the user extensibility in the Oracle9i Designer repository you have to load the user extensibility in a fresh Oracle Designer 6.0 repository before loading any application system. You have to load the Oracle Designer 1.3.2 user extensibility into an Oracle Designer 6.0 repository only if you apply the migration strategy via extracted application systems.

### Migration via the Repository Administration Utility Upgrade tool

If you have chosen the "migrate entire repository content" migration strategy (see above), install the Oracle Designer 6.0 client software and launch the Upgrade utility from the Oracle Designer 6.0 Repository Administration Utility to bring your entire repository content forward to Oracle Designer 6.0.

### Migration via extracted application systems

Use the application restore option (available in the Repository Object Navigator) if you have chosen the sub-selection migration strategy (see above).

Note that you have to select a coherent set of application systems in order to circumvent skeleton application systems. Note also that it requires additional migration effort if any changes are applied to the selected application systems in the Oracle Designer 1.3.2 repository after the migration has taken place. You may use the freeze application system option (as a rather rigid method) to prohibit any changes in the Oracle Designer 1.3.2 repository just after the migration.

You should verify the migration logging in the repadm60\log directory before moving on to the Oracle9i Designer migration.

## Migration steps from an Oracle Designer 6.0 repository to Oracle9i Designer repository

Apply the following migration steps if your current release of Oracle Designer is 6.0:

- Load the User Extensibility
- Launch the migration wizard
- Check in structured elements

### Unload Oracle Designer 6.0 user extensibility (optional)

Obviously you can skip this activity if you have not defined any user extensibility or if you do not want to bring forward the user extensibility into the Oracle9i Designer repository

In order to keep your user extensibility you first have to unload the Oracle Designer 6.0 user extensibility. The unload option is available from the Oracle Designer 6.0 RAU utility.

### Load Oracle Designer 6.0 user extensibility into Oracle9i Designer (optional)

If you want to bring forward the user extensibility into the Oracle9i Designer repository you first have to load the user extensibility in a fresh Oracle9i Designer repository before migrating any application system. You always have to load the Oracle Designer 6.0 user extensibility into a fresh Oracle9i Designer repository for both migration strategies.

### Launch the migration wizard

Read the migration section of the Oracle9i SCM Repository Installation Guide before launching the migration wizard.

The Oracle9i Designer migration method for structured elements has changed significantly. An Oracle Designer 6.0 repository will not be upgraded to an Oracle9i Designer repository during the migration. The Oracle Designer 6.0 repository content (or part of it) will be copied into a fresh installed (or already populated) Oracle9i Designer repository.

It should be noted that the migration wizard will actually clean up your Oracle Designer 6.0 repository. The migration wizard will for example correct invalid references, populate missing properties, update invalid properties or force delete duplicate values. This cleanup is optimized for Oracle9i Designer. You should therefore not reuse your Designer 6.0 repository for these application systems that are migrated to Oracle9i Designer. You should use a target shadow Oracle Designer 6.0 repository if you are still planning to use Oracle Designer 6.0.

The migration wizard allows you to connect to an Oracle Designer 6.0 repository and subsequently select one or more application systems. Apply the specific migration strategy as discussed before.

The wizard will verify if there are any incoming shares from other application systems that were not selected. These application systems will be added to the selection in order to circumvent skeleton application systems. A skeleton application system only captures the objects that are shared to one or more other application systems. It does not contain all objects. The selection of a coherent set of application systems is extremely important. Note that coherency is not only about receiving shares but also about outgoing shares. For example if you migrate the single application QMS505 (1) first and secondly the application HSD505(1) you would receive QMS505(1) again because of the incoming shares of QMS505 to HSD505. See the example of a quickscan ERD given in the section "Preparing (cleaning up) your 'old' repository content", above. You should however not re-select an application system that has already been (implicitly) migrated. In this example you should migrate HSD505 and QMS505 as a set.

The wizard will populate a workarea called GLOBAL_SHARED_WORKAREA with the migrated data if your repository is not version enabled.

The wizard will populate the migrated data in a new system generated workarea if your repository is (already) version enabled. The name of that workarea will be based upon the connect string (e.g. WA_des60_ds6). You should verify the Workarea rule of this system generated workarea. You should change this rule to your own specifications if it contains the following rule INCLUDE_FOLDER(SYSTEM FOLDER{MAIN;LATEST}) and if you are planning to check in the structured elements. This specific rule will evaluate the content of the system folder only after you have checked in your structured elements. It will not display your structured elements. You will find more information about workarea and workarea rules in a paper by Lucas Jellema, called "Interior Oracle9i Designer" published for the ODTUG2000 and in Chapter 6 "Reorganize a migrated Oracle9i Designer repository". Note that you cannot reuse previously created workareas.

You can control, as in Oracle Designer 2.1.x and Oracle Designer 6.0, to a certain extent, the migration operation while it is in progress. The migration operation is divided into a number of stages. You can pause and restart the current stage, retry or skip a stage that failed, or abandon the whole operation.

The Control Status dialog box is displayed while the upgrade is in progress, and includes a number of buttons for the different controls.

For example, if you ran out of extents in the rollback segment during an upgrade, you could pause the upgrade at its current stage, allocate a larger rollback segment, then restart the upgrade from the stage where the failure occurred.

It is highly recommended that you verify the content of the migration log files, written to the ORACLE_HOME\repadm61\logs directory, during or after the migration.

Application systems are migrated as application systems suffixed with the application version number (e.g. "HSD505 (1) or QMS505 (1)") and not as (root) folders. There is no option (yet) to transfer application systems as (root) folders (or vice versa).

The Oracle9i Designer repository content may look as follows just after the migration of your structured data:

### Check in structured elements

If you do not want to enter the versioned world (yet) you may skip this activity.

The migration wizard groups all migrated application systems initially either in a default workarea called GLOBAL_SHARED_WORKAREA or in a specific migration workarea (e.g. WA_DES6I_DES6I) if you have a version enabled repository.

Execute the following steps if you do want to enter the versioned world.

- Verify the access rights of the repository owner against the workareas and the underlying containers.
- Check in all structured objects via the "List Checkouts" option

#### Verify the access rights

Verify the access rights against the (default) workareas and migrated application systems of the Oracle9i Designer repository owner. The Oracle9i Designer repository owner must have the version privilege for both objects in order to check in the objects within the context of workareas. The following shows access rights against workareas and application systems:

Note that you can select multiple workareas and application systems at the same time - via a discontinuous select - to review and define the access rights for the specific user.

#### Check in structured objects

The migration wizard has loaded your structured elements in the repository, but it did not check in the objects. The Oracle9i Designer Repository Object Navigator has an option to check in all non-versioned objects simultaneously. This "List Checkouts" option is available for each container via the right mouse button and will launch the List CheckOuts Criteria dialog:

In the context of migration you are only interested in a list of "non-versioned" objects.

Clicking the OK button will launch a window with all non-versioned objects for the highlighted container:

You can check in only owned non-versioned objects. You cannot check in non-owned short-cuts. These objects should not be highlighted in the list, while checking in all non-versioned objects.

It is very useful to apply the same checkin notes (e.g. "Initial creation") for all non-versioned objects in the checkin windows, as illustrated below:

You should realize that once you have checked in your first object(s) you actually have entered the versioned world. From that moment on you cannot re-enter the non-versioned world - other than by recreating a fresh Oracle9i Designer repository and re-starting the migration in a non-versioned mode. The checkin operation is an irreversible action.

Checkingin of the subordinate non-versioned objects via the "List Checkouts" option does automatically imply a checkin of the application system. Most likely you would like to apply your naming standard for application systems or containers in general. For example, you could change the default migration application name "HSD505 (1)" into HST and "QMS505 (1)" into QMS just before the batch checkin of all subordinate objects. Note also that you have to check out an object to apply any changes - including the name of the application system.

## Post migration steps for structured data

This stage covers activities for structured data that are not handled by the migration wizard:

- Remove the suffix (1) from your migrated application system name.
- Translate (old) parent application systems to a nested container structure.
- Build a version tree for structured data.
- Verify your migration result.
- Reevaluate preference sets.

### Remove the suffix (1) from your migrated application system name

Remove the suffix (1) or any other version indication suffix from your migrated application system name. The command line tool may not cope with suffixes appropriately.

### Translate (old) parent application systems to a nested container structure

Skip this activity if you have not defined a hierarchy of application systems (also known as parent application systems) in previous releases of Oracle Designer.

You should realize that the implementation of application systems hierarchies is quite different in Oracle9i Designer to the implementation of application system hierarchies in releases of Oracle Designer before 6i. Oracle9i Designer allows you to define a hierarchy of containers: application systems may contain other application systems or folders. Folders may contain other folders or application systems. All containers - no matter their position in the hierarchy - could contain subordinate objects (e.g. entities, tables) in Oracle9i Designer as opposed to previous releases in Oracle Designer. In previous releases of Oracle Designer only subordinate application systems could contain subordinate objects.

Reconsider therefore the application system hierarchy before and after the migration. Note that you should have removed the parent/child relationship between application systems prior to migration.

### Building a version tree for structured data

Skip this activity if you do not want to enter (yet) the versioned world or if you do not (yet) want to have multiple object versions.

The only way to store multiple object versions in releases of Oracle Designer before 6i was by the creation of an additional application system via archive/restore, or by versioning an application system. Within these additional application systems you could store the same object (name) of the same type with a different definition. These different object definitions represented another object version.

The migration wizard will not migrate these different object versions as a version tree. The migration wizard will handle these object versions as totally different objects.

#### Build a version tree manually

The manual build of a version tree of structured elements comprises the following steps (see also the illustration that follows):

1. Check out the context element (with the lowest version definition) from the default migration workarea (e.g. QMS_MESASAGE_TXT [1.0]).
2. Apply the changes manually based upon the definitions captured in QMS505_DEV (1)\ QMS_MESASAGE_TXT .
3. Compare the two versions with the compare utility and verify this result with the Oracle Designer 1.3.2 environment. You can launch the compare prevision version utility directly via the checked out object.
4. Check in the manually changed version of the object (e.g. QMS_MESASAGE_TXT [1.1]).

Repeat steps 1 to 4 until no more additional versions need to be built manually.

### Post migration steps for structured elements within a staged migration approach

The next section will discus the merge steps for structured elements if you have adopted a staged migration approach (as discussed in the section "Migrate a sub-selection of application system", above).

#### Merge interim changes in structured elements

Apply the following steps for structured elements to bring the interim changes forward in Oracle9i Designer.

1. Create a workarea called WA_<ddmmyyyy> with rule LATEST_BEFORE that represents a snapshot of your repository just after the initial checkin of your structured elements (and files). Note that this workarea also represents the content of your "original" repository before any interim changes have been applied. You should not allow anyone to make any changes via this workarea.
2. Isolate the changed structured elements in a User Defined Set in your non-9i repository.
3. Isolate the changed structured elements in a User Defined Set in your Oracle9i Designer repository.
4. Migrate all application systems which contain a specific User Defined Set to Oracle9i Designer via the migration wizard.
5. Check out (if possible) all objects that are associated with the specific User Defined Set in Oracle9i Designer.
6. If the object is already checked out then you have to merge the interim changes with the changes applied in Oracle9i Designer.
7. If the checked in object version is higher than the object version in WA_<ddmmyyyy> you also have to merge the interim changes. In the following illustration, you have to merge the interim changes since the interim changes are based upon version 1.1.

  8. If the checked in object version equals the object version from WA_<ddmmyyyy> then you can bring all interim changes forward in Oracle9i Designer.

Step 8 may be supported by the export/import method as described earlier in section Build a version tree for structured elements via the export/import utility.

Step 6 or 7 (if applicable) must always take place manually. You can however effectively use the compare utility between the latest version of the object and the similar object in the migrated application.

### Verify the migrated structured data

Apply the following checklist for your migrated structured data:

- All selected application systems in your Oracle Designer 6.0 repository should also be available in the Oracle9i Designer repository.
- All shares should be translated as "short cuts".
- Your version tree - if applicable - should be comparable with your "object versions" captured in diferent application systems in previous releases of Oracle Designer.

### Compute statistics

To avoid a degradation in repository performance, we recommend that you run the Compute Statistics utility (available at the Oracle9i Designer RAU tab sheet) regularly, and especially after an operation that significantly affects the size of the repository.

Note that the migration automatically launches a compute statistics stage. Therefore you do not have to run the compute statistics directly after a migration.

In Oracle9i Designer, you can run the utility directly from the Repository Administration Utility window by clicking the Compute Statistics button:

In most cases, we recommend using a higher figure than the default (e.g. 50%). However, if your repository has large tables, it is especially important to use lower figures for the sample size, as higher figures will cause the compute operation to take a long time to complete.

In addition it is highly recommended to implement a daily batch mechanism that computes the statistics of the dynamic repository tables.

### Reevaluate preference sets

The handling of the preference sets reevaluation on application system level or lower for your Oracle Developer and WEB PL/SQL components takes place in Part 4 and Part 5 of this guide respectively.

# Chapter 4 Migrate files from third party source control tools

The migration of files, stored in a third party source control tool, should typically start after the migration of the structured elements. Only then are you able to integrate your files with the structured elements - both type of elements will then share the same root-container.

The migration of files into Oracle9i Designer comprises the following steps:

- Populate the file system with a baseline set of files
- Populate the Oracle9i Designer repository

Skip this chapter if you have not stored your files in a third party source control tool. (e.g. PVCS/VM, ClearCase, Visual Source Safe).

The migration of files stored in a third party source control tool will be clarified using an abstract of 'Headstart 5.0.5' files. It is assumed that the files are captured in two project databases in PVCS/VM : HST and QMS respectively (as illustrated below).

PVCS/VM is a source control tool like ClearCase or VisualSource that supports the storage of multiple file versions, workspace procedures and several other configuration management procedures.

## Populate the file system with a baseline set of files

The migration of files will be based upon the file upload functionality in Oracle9i Designer. The migration strategy of files will not be based upon an interpretation of the third party source control repository.

The migration steps for files stored in a source control tool will be illustrated by using PVCS/VM as an example. Note that you could apply the same migration strategy for files stored in other source control tools (e.g. ClearCase, Visual Source Safe). Most likely these other tools have similar options available to publish your repository content - via a specific filter - on the file system.

The publication of a baseline file set should typically be organised in the following stages:

- Get an overview of your third party source control tool repository.
- Clean up your third party source control tool repository.
- Determine a generic directory structure.
- Publish the baseline set of files on the file system.

### Get an overview of your third party source control tool repository

Your third party source control may have several reports or options available to visualise the repository content of file versions. Such an overview will effectively support you with the publication of a baseline set of files.

For example PVCS/VM offers an option to export the administrative information (e.g. projects, files, file versions, group association with file versions) into an Oracle database. Subsequently you can build reports (using SQL*Plus) to generate an overview of your PVCS/VM repository content that may look as follows:

    PRJ Filename                   Develop  Test  Accept  Prod

    HST upg501.sql                 1.0

    HST announcement.doc           1.2      1.1   1.0     1.0

    HST elcheapo.pl                1.0      1.0   1.0     1.0

    QMS qmsolb50.olb               1.7      1.6   1.6     1.6

Note: Appendix A contains an example of a SQL query - based on the PVCS/VM administration tables - that has generated the above report.

The above report is based upon the functionality in PVCS/VM that enables you to associate one or more promotion groups - see report headers - to a specific file version. In PVCS/VM you can also associate one or more release labels to a specific file version. You could generate a similar report with release numbers in the column headers instead of promotion groups.

The PVCS/VM content for the file announcement.doc should look as follows:

Note that the exported PVCS/VM administrative information is static. It does not reflect any changes after you have exported the data from the PVCS/VM repository. You should therefore export the administrative data multiple times if there are any cleanup activities based upon the first output - and that is most likely to happen.

### Clean up your third party source control tool repository

The upload is an excellent opportunity to clean up your repository content of the third party source control tool. You can apply the following clean-up checklist for files captured in third party source tools, using the overview, as discussed in the previous section:

- Remove unused containers and/or sub-containers. The equivalent of a container in PVCS/VM is called a project database and a sub-container is called a project.
- Remove obsolete files.
- Remove obsolete (interim) object versions. Candidate obsolete or interim file versions are file versions that are not used or associated with a release or a promotion level.

### Determine a generic directory structure

The upload will not only capture the files, but also the owning directories. You should therefore investigate the content of the source control tool for each specific project (or any other root grouping vehicle) in terms of (sub)folders and file types. Subsequently you can determine a generic directory structure based upon this investigation.

Example: Your files in a specific project database could already been organized in a specific (nested) folder structure (see the illustration below) or you could group your files in one or more sub-folders based upon the file extension if your project database is not organized in sub-folders.

The illustration above shows that a directory structure for HST and QMS is already available. If such a structure is not yet available you could set up a directory structure based upon your file system structure HST and QMS respectively.

### Publish the baseline set of files on the file system

Your third party source control tool probably supports the functionality to publish a set of files of a specific version based upon the promotion group association or a release label association. Specifically, this "get" option is very effective for the migration of files. You can use this option to publish a baseline set of your files to a specific destination directory structure. For example you could publish all your file versions that are associated with the group 'development' (as shown in the dialog below) to the stage area 'f:\stage\hst\' or you could start to publish all your file versions that are associated with version label 5.0.5. The "Get" option in the screen dump below will publish all file versions and its owning folders and subfolders that are associated with the promotion group "development" to directory f:\stage\hst .

The window above depicts the promotion group association in PVCS/VM against file versions. The 1.1 version of the elcheapo.doc file is associated with the promotion group "Development" while the 1.0 version of is associated with "Production".

Note that if you want to bring forward multiple file versions (see the section "Building a version tree for files"), you have to start with a baseline or lowest version in the publish step. Your baseline version will probably be captured in the production environment. If you do not want to bring forward multiple file versions you have to "get" and upload the latest file versions. These latest versions are probably associated with the "development" promotion group.

Your (populated) file system may look as follows after the (first) publish operation for project HST for the sub-folder scripts.

Note that you may have to move your files after the publish operation to a specific sub-directory if you did not organize your sources in a specific sub-folder structure beforehand. The move operation should typically be based upon the output of your investigation to a generic directory (see also the section "Determine a generic directory structure").

Your third party source control tool may also have publish options that are accessible from the command line interface or via an API. For example PVCS/VM offers a GET option via a Command Line Interface in a 'DOS' session that allows you to get a multiple set of file versions either based upon a release label or a promotion group. Therefore you may prefer the Command Line Interface instead of the GUI interface to execute the publish operation as a batch job.

## Populate the Oracle9i Designer repository

In this activity you will populate the Oracle9i Designer repository with the (first) set of files. The populate operation is divided into two steps:

- Apply (root) folder mapping
- Upload the files - and check in if applicable

Every insert, update or delete operation on the Oracle9i Designer repository must be executed within the context of a specific workarea.

If you are not planning to enable the repository for versioning you have to use the default migration workarea GLOBAL_SHARED_WORKAREA.

Otherwise you can use any workarea for the migration of files since you have the intention to check in the file objects. Note that every checked in object can be accessed eventually in every workarea (depending on the workarea rules).

### Apply (root) folder mapping

The upload (and check-in of files if applicable) must be preceded by a folder mapping. The "Map Folder to the File System" option is available for each root container - at the right mouse button for a specific root container.

This folder mapping option allows you to upload the file system content (directory and files) with the repository. See below.

For example the directory "f:\stage\hst\" will be mapped to the HST container and the directory "f:\stage\qms\" will be mapped to the QMS container. See below.

Note that the files - and their folders and subfolders - in the Headstart example will be uploaded (and checked in if applicable) against the existing containers (e.g. HST and QMS). Obviously you could also bring the files forward in other or new "to be created" containers.

### Upload of files

The upload will actually store the files in the repository. In addition it will also bring all directories and sub-directories forward if you have enabled the "Recurse into sub-directories" option (see the following dialog box). It is therefore important that you have applied a generic folder structure, since that structure will be loaded in the repository as well.

### Checkin of files

Skip this section if you do not want to enter the versioned world.

If you want to check in your files, you can either combine the upload with a check-in or you can use the "list checkouts" option (as with the structured elements). The check-in of files will actually apply a version number to the stored files.

As with structured elements you should realise that once you have checked in your first file(s) you have actually entered the versioned world. From that moment on you cannot re-enter the non-versioned world - other than by re-creating a fresh Oracle9i Designer repository and re-starting the migration in a non-versioned mode. The check-in operation is an irreversible action.

Note that you can verify the "check-in" status of all file elements (including folders) via the "list checkouts" option per root-container. Eventually this option should not feed back any file elements.

The container and sub-container structure for application system HST looks as follows after the upload and check-in operation:

### Upload and check in sources and executables

Next to the storage of structured elements you may consider the upload and check-in of the derived sources and corresponding executables. For example you could also upload the derived Oracle Forms FMB source (e.g. HSD0004F.FMB) and corresponding executable (e.g. HSD0004F.FMX) next to the migrated structured form itself (Oracle Forms 60 module HSD0004F). In addition you could also upload multiple representations of your sources and executables, for example Forms50 and Forms60. You can organise your multiple representation either via different folders (e.g., demof50, demof60) or via the use of different labels.

With all representations available in the repository you could instantly build your environment (via the download option) from the repository content without the derivation (or generation) step from a structured format into a derived source and executable. You can then gradually replace the source and the executable with the new generated and compiled representation over time. Your Oracle9i Designer repository can act as a single point of control just after the migration - it captures all your application objects necessary for a 'runtime' environment, as below:

## Post migration steps for files stored in a third party source control tool

There are the following (possible) post migration steps for files:

- Build a version tree for files
- Verify the migrated files
- Compute statistics

### Building a version tree for files

It is quite easy to build a version tree for files stored in a third party source control tool (compared with structured elements).

Skip this activity if you do not (yet) want to enter the versioned world or if you do not (yet) want to have multiple object versions of files.

If you want to bring forward multiple file versions you have to start with a baseline or lowest version in the publish step as discussed above. Obviously the version tree should be built starting from the lowest version.

If you are planning to build a version tree, you can build it either:

- immediately, or
- in time.

The build of a version tree for files should be based upon an overview as was presented in the section "Get an overview of your third party source control tool repository", above. Such an overview of the third party source control content, i.e. which file versions are available and with which promotion groups or release labels are these file versions associated, is not only very productive, but also quality-effective for verification purposes.

#### Building a version tree immediately

In this activity you will bring one or more file versions forward immediately from your third party source control tool to Oracle9i Designer.

Building a version tree (immediately) comprises the following task steps:

1. Check out the relevant file in Oracle9i Designer (with a lock) that has multiple versions in your third party source control.
2. Get the file from your third party source control (without a lock) and overwrite the file on the file system in the prepared directory.
3. Upload and check in the file in Oracle9i Designer.

These steps are illustrated below for the file Announcement.doc.

Repeat these steps for each file that needs multiple versions and for which no more versions are available in your third party source control tool. For example file Announcement.doc has 3 versions (1.0, 1.1 and 1.2) and therefore you have to repeat this activity twice.

Building a version tree for files (immediately) should typically be performed by a developer. You therefore have to give intermediate access to developers that are responsible for these post-migration activities. Consult Chapter 7 "Migrate users and assign access privileges" for guidelines on repository access rights to the repository itself, to workareas and to containers.

Note that it is not necessary to run the compare utility after a build of another version. The build of another version is not as complex as with structured objects. Note also that the Oracle9i Designer repository has not implemented any kind of delta storage method while storing another file version. Another file version is just stored completely. In addition you can store a file in the repository either compressed or uncompressed.

Finally note that the above scenario can be very time consuming if you have many files with many file versions. You can then speed up the process by checking in only relevant file versions. For example only document1.doc version 1.0 and version 1.2 are used, while document version 1.1 is not used anywhere anymore. In this specific example you only need one extra activity to check in document1.doc version 1.2.

#### Building your version tree in time

During this activity you are building the version tree in time. You execute the check-out and check-in steps (as described and illustrated in the previous paragraph) whenever you need an additional version of a file. Your third party source control tool will be kept 'alive' (in read-only mode) as long as you need additional versions.

If you apply this migration method, you will also start with the lowest available file version, since you are eventually interested in the version tree. You can only build a version tree starting from the initial version.

You have to bring forward the additional file versions in the following circumstances:

- Setup of another promotion environment that involves versions other than those already available in Oracle9i Designer.
- Setup of another release that involves versions other than those already available in Oracle9i Designer.
- The continuation of development of one or more object versions that are not yet available in Oracle9i Designer.

#### Summary of migration strategies for building a version tree for files

Several options for building a version tree for files stored in a third party source control tool were described in the previous paragraphs. The following strategies are relevant if you combine these options:

1. The build of a version tree for files is not yet planned.
2. The build of a version tree for all file versions will be built immediately.
3. The build of a version tree for only a limited number of file versions will be built immediately.
4. The build of a version tree for only a limited number of file versions will be built in time.

> The table below presents an overview of these options, which baseline version (lowest or latest) should be loaded initially and when you should choose for a specific strategy.

# | Build of version tree? | Baseline version | Multiple versions? | Rationale
--- | --- | --- | --- | ---
1 | Not planned (yet) | Latest | Single | Oracle9i Designer will not enter the versioned world yet because (most) projects are within development. In addition there are only a limited number of different versions
2 | Immediately | Lowest | Multiple (all) | The number of files and different versions is limited or the migration can and will be organized via batch jobs (despite the large numbers of files and versions). The investment in collecting a batch utility for migrating your files can very well be justified. Note. A batch job for downloading the files from PVCS/VM and subsequently uploading the files into Oracle9i Designer - to build the version tree - can be based upon the available Command Line Interface of PVCS/VM and the Command Line Interface of Oracle9i Designer respectively.
3 | Immediately | Lowest | Multiple (limited number) | There are only a few differences in object versions between the different environments and/or releases. The build effort of version trees is therefore limited.
4 | In time | Lowest | Multiple (limited number) | The number of different file versions is substantial, but there is on the other hand a time constraint on the migration period.

Note that you can only select the most optimal strategy if you have full knowledge about the content of your third party source control tool. Again the report presented in the section "Get an overview of your third party source control tool repository", above, is a very productive way to support your strategy for building version trees.

### Verify the migrated files

You can verify your migration effort for files for the following dimensions:

- Verify the file existence
- The existence of the appropriate number of additional versions (version tree)

#### Verify the file existence

The Oracle9i Designer repository should contain the same number of files as in the third party source control tool, unless one or more files are deliberately not brought forward to the Oracle9i Designer repository.

You can use the Repository Object Navigator to view the file objects (see for example the illustration in "Check-in of files", above) or even better you can use the API to produce a list of file objects for each root-container.

#### The existence of the appropriate number of additional versions (version tree)

The Oracle9i Designer repository should contain the appropriate number of file versions (or version tree) as was available in the third party source control tool.

Note that the exact number of file versions may deviate from the original number of file versions depending on the specific migration strategy for building a version tree for files (see previous paragraph).

Note also that the version number itself may deviate from the file version number if you have not brought forward all file versions and at the same time you have opted for the automatic numbering policy.

You can use the Version History Viewer (see below) to look up a version tree. Subsequently you can use the report presented in "Building a version tree for files" to compare the result in Oracle9i Designer with the content of your third party source control tool.

### Compute statistics

Now is a good time to rerun "Compute Statistics" since your repository content is expanded with file objects (and maybe additional file versions). Running "Compute Statistics" will avoid a degradation in repository performance.

In Oracle9i Designer, you can run the utility directly from the Repository Administration Utility window by clicking the Compute Statistics button:

# Chapter 5 Migrate files that are stored on the file system

The migration of files, stored on the file system, should typically start after the migration of the structured elements. Only then are you able to integrate your files with the structured elements - both type of elements will then share the same root-container.

The migration of files into Oracle9i Designer comprises the following steps:

- Populate the file system with a baseline set of files
- Populate the Oracle9i Designer repository

Skip this chapter if you have already migrated your files from a third party source control tool or you do not (yet) have any files to migrate.

The migration of files stored on the file system will be clarified using an abstract of 'Headstart 5.0.5' files. It is assumed that the files are stored on the file system as depicted below:

## Populate the file system with a baseline set of files

The migration of files will be based upon the file upload functionality in Oracle9i Designer.

The publication of a baseline file set should typically be organized in the following stages:

- Restructure your file system content
- Publish the baseline set of files on the file system.

Note that your file structure containing your candidate files could be stored on a local drive, a network drive or even on a Unix file system. Obviously in the case of a Unix file system you should have installed certain software (e.g. Samba) to make the Unix file system transparent - presented as a network drive - on your NT or Windows95/98 workstation.

### Restructure the file system

The upload is an excellent opportunity to restructure your file system. It is highly recommended to use a staging area - a separate directory structure - in order not to interfere with ongoing development, testing or even production.

The restructure of the file system comprises the following stages:

- Determination of a generic directory structure
- A clean-up of your file system

#### Determination of a generic directory structure

The upload will not only capture the files, but also the owning directories. You should therefore investigate the file system content for each specific root directory (e.g. HST, QMS) in terms of (sub)folders and file types. Subsequently you can determine a generic directory structure based upon this investigation and create this generic structure in the staging area.

#### Clean-up checklist

Consult the following checklist to limit the number of files for uploading.

- Obsolete objects
- Temporary files
- Compiled object versions
- Multiple instances
- "out of context" objects

Applying the above checklist will result in an effective base line set, that you can upload and check in to Oracle9i Designer.

It is assumed that the content in the staging area for HST and QMS, depicted at the beginning of this chapter, is satisfactory (for example, no clean-up actions are necessary).

## Populate the Oracle9i Designer repository

The procedure for populating the repository with files stored on the file system in Oracle9i Designer is the same as for files stored in a third party source control tool, once you have populated the files in the staging area.

Consult therefore "Populate the Oracle9i Designer repository" in Chapter 4 for a complete overview of the population steps.

## Post migration steps for files stored on the file system

There are the following (possible) post-migration steps for files:

- Build a version tree for files
- Verify the migrated files
- Compute statistics

### Build a version tree for files

Skip this activity if you do not (yet) want to enter the versioned world or if you do not (yet) want to have multiple object versions of files.

Compared with the storage of files in a third party source control tool, it is much harder to build up a version tree for files that are stored on the file system. It is more difficult to build an overview (see the illustration below) because additional versions of a file must either be stored under a different name or at a different location.

If you want to bring forward multiple file versions, you have to start with a baseline or lowest version in the publish step as discussed above. Obviously the version tree should be built starting from the lowest version.

The build of a version tree for files should be based upon an overview of your file system content, i.e. which file versions are available in which specific directories.

Your overview may look as follows:

    Dir Filename                         Version

    HST announcement.doc

    HST \hst\prd\doc\ announcement.doc   1.0

    HST \hst\acc\doc\ announcement.doc   1.0

    HST \hst\tst\doc\ announcement11.doc 1.1

    HST \hst\dev\doc\ announcement12.doc 1.2

    QMS qmsolb50.olb

    QMS \qms\prd\demof60\ qmsolb50.olb   1.6

    QMS \qms\acc\demof60\ qmsolb50.olb   1.6

    QMS \qms\tst\demof60\ qmsolb5016.olb 1.6

    QMS \qms\dev\demof60\ qmsolb5017.olb 1.7

Probably the only way to build such an overview is to investigate the file content file-by-file, based on the different file versions (either captured using another file name or in another location).

Building a version tree for files should typically be performed by a developer. You therefore have to give intermediate access to developers that are responsible for these post-migration activities. Consult Chapter 7 for guidelines on repository access rights to the repository itself, to workareas and to containers.

Note that it is not necessary to run the compare utility after a build of another version. The build of another version is not as complex as with structured objects. Note also that the Oracle9i Designer repository does not implement any kind of delta storage method while storing another file version. Another file version is just stored completely. In addition you can store a file in the repository either compressed or uncompressed, to minimize the size of your repository.

If you are planning to build a version tree for files, you can either build it:

- immediately or
- in time.

#### Building a version tree immediately

In this activity you will bring one or more file versions forward immediately from your file system to Oracle9i Designer.

Building a version tree (immediately) comprises the following task steps:

1. Check out the relevant file in Oracle9i Designer (with a lock) that has multiple versions in your third party source control.
2. Copy the 'next version' to your work directory. You will deliberately overwrite the file on the file system in your work directory. Note that you may have to rename the file if another version was captured with a different name.
3. Upload and check in the file in Oracle9i Designer.

These steps are illustrated below for the file Announcement.doc.

Repeat these steps for each file that needs multiple versions and for which no more versions are available. For example, file Announcement.doc has three versions (1.0, 1.1 and 1.2) and therefore you have to repeat this activity twice.

#### Building your version tree in time

In this activity you will bring one or more file versions forward in time from your file system to Oracle9i Designer.

Building a version tree (immediately) comprises the following task steps:

1. Check out the relevant file in Oracle9i Designer (with a lock) that has multiple versions in your third party source control.
2. Copy the 'next version' to your work directory. You will deliberately overwrite the file on the file system in your work directory. Note that you may have to rename the file if another version was captured with a different name.
3. Upload and check in the file in Oracle9i Designer.

These steps are the same as for building a version tree immediately. Consult therefore also the illustration in "Building a version tree immediately", above.

Repeat these steps for each file that needs multiple versions and for which no more versions are available. For example, file Announcement.doc has three versions (1.0, 1.1 and 1.2) and therefore you have to repeat this activity twice.

Finally note that the above scenarios can be very time consuming if you have many files with many file versions. You can speed up the process by checking in only relevant file versions. For example only Announcement.doc version 1.0 and version 1.2 are used, while announcement.doc version 1.1 is not used anywhere anymore. You only need one extra activity to check in Announcement.doc version 1.2.

#### Summary of migration strategies for files stored on the file system

Several options for building a version tree for files stored on the file system were described in the previous paragraphs. The following strategies are relevant if you combine these options:

1. The build of a version tree for files is not yet planned.
2. The build of a version tree for all file versions will be built immediately.
3. The build of a version tree for only a limited number of file versions will be built immediately.
4. The build of a version tree for only a limited number of file versions will be built in time.

The table below presents an overview of these strategies, which baseline version (lowest or latest) should be loaded initially and when you should choose a specific strategy.

# | Build of version tree? | Baseline version | Multiple versions? | Rationale
--- | --- | --- | --- | ---
1 | Not planned (yet) | Latest | Single | Oracle9i Designer will not enter the versioned world yet because (most) projects are within development. In addition there are only a limited number of different versions
2 | Immediately | Lowest | Multiple (all) | The number of files and different versions is limited.
3 | Immediately | Lowest | Multiple (limited number) | There are only a few differences in object versions captured in different directories. The build effort of version trees is therefore limited.
4 | In time | Lowest | Multiple (limited number) | The number of different file versions is substantial, but it is too time consuming to bring all versions forward at once.

Note that you can only select the most optimal strategy if you have full knowledge about the content of your file system. The report featured in "Building a version tree for files", above, is a very productive way to support your strategy for building version trees for files.

### Verify the migrated files

You should verify your migration effort for files for:

- the file existence
- the existence of the appropriate number of additional versions (version tree)

#### Verify the file existence

The Oracle9i Designer repository should contain the same number of files as stored on the file system. Unless one or more files are deliberately not brought forward to the Oracle9i Designer repository.

You can use the Repository Object Navigator to view the file objects (see for example the illustration in "Check-in of files", above) or even better you can use the API to produce a list of file objects for each root-container.

#### The existence of the appropriate number of additional versions (version tree)

The Oracle9i Designer repository should contain the appropriate number of file versions (or version tree) as was available in the third party source control tool.

Note that the exact number of file versions may deviate from the original number of file versions depending on the specific migration strategy for building a version tree for files (see previous section).

Note also that the version number itself may deviate from the file version number if you have not brought forward all file versions and at the same time you have opted for the automatic numbering policy.

You can use the Version History Viewer (see below) to look up a version tree. Subsequently you can use the report presented in "Building a version tree for files" to compare the result in Oracle9i Designer with the content of your third party source control tool.

### Compute statistics

Now is a good time to rerun "Compute Statistics" because your repository content is expanded with file objects (and maybe additional file versions). Running "Compute Statistics" will avoid a degradation in repository performance.

In Oracle9i Designer, you can run the utility directly from the Repository Administration Utility window by clicking the Compute Statistics button:

# Chapter 6 Reorganize a migrated Oracle9i Designer repository

The migration of structured elements and/or files should be followed by reorganisation activities. These reorganization activities involve the implementation of a specific implementation of your promotion model.

The following subjects are discussed in detail:

- Define workareas and configurations
- Remove obsolete elements
- Compute statistics

There are only a limited number of reorganization options available in a non-versioned world. For example you cannot create additional workareas next to the default 'GLOBAL_SHARED_WORKAREA'. You can only populate checked in objects in another workarea, but there are no checked in objects in a non-versioned world. Also you cannot create configurations since the configuration membership is based only upon checked in objects. Again no objects are checked in in a non-versioned world. You can only (re)organize your repository through (nesting of) containers in a non-versioned world.

You will find other and more comprehensive uses of workareas and configurations in a paper by Lucas Jellema called "Interior Oracle9i Designer" for the ODTUG2000 conference.

## Define workareas and configurations

A promotion model can be implemented with a combination of workareas and configurations. If you adopt this specific implementation then basically all workareas - except the development workarea - will be based upon configurations.

In this section we assume that your promotion model looks as follows:

> Development

> System test

> System integration

> Production

> Production fix

Obviously your promotion model may have more or fewer promotion levels.

In this specific promotion model implementation you will create workareas that represent promotion environments. In addition you may want to restrict each workarea in each promotion environment to one or more sub-systems. For example you will create a workarea for the development environment that contains the latest folder content of folders HST and QMS. A workarea for the test environment will be applicable to the same sub-systems, but it is based on different workarea rules. For example the workarea WA_TST_HSD represents the test environment for HST and QMS and is based on base line and patch configurations of HST and QMS. The term base line and patch configurations will be explained below.

The following workarea rules are applicable in the above described promotion model:

> "LATEST(MAIN)" for the development workarea or "INCLUDE_FOLDER" if you break up your repository in different areas

> "INCLUDE_CONFIG" for example for the production or system test workarea

All non-development workareas will be based on configurations. You could classify two types of configurations:

> A configuration representing a specific (full) release or base line of a specific root container (e.g. HST_505).

> A configuration representing a patch consisting of a limited number of configuration items owned by a specific root container and applicable for a specific base line (e.g. HST_505_10).

Obviously you can create the non-development workareas only if you have defined one or more configurations. You can create configurations (baselines and patches) via the configuration wizard.

You can either populate a configuration via a combination of rules - similar to the population of workareas - or you can just select objects from the repository (see the illustration above). Configuration rules are evaluated once and result in a set of specific object versions. The configuration rules are not saved as workarea rules are.

You should verify that your configurations not only include the structured elements but also the files (captured in folders). You will use the folders and files inclusion later on to build (or synchronize) your file system in each of your promotion environments (see Chapter 8).

With one or more configurations you are able to create your non development workareas with the workarera wizard.

"Base line" configurations can effectively be created via configuration rules, while "patch" configurations can be created via selecting the individual object versions.

The order in which you specify the workarea rules is very important. The workarea rules are evaluated from top to bottom. Another object version will not be evaluated whenever an object version is already populated by a 'higher' order workarea rule.

Your workarea for a specific promotion environment should eventually include one or more baseline configurations and/or one or more corresponding patch configurations of corresponding interrelated containers, as illustrated above.

Omitting one or more configurations may result in an incomplete definition of your components. For example your module definition will be incomplete if you omit the configuration that captures your preference sets that were initially defined (in the development environment) against your module.

Note that your development workarea ('WA_DEV_HSD') has a much more dynamic character than your 'other' workareas since your development workarea is based upon the 'simple' rule LATEST(MAIN) or FOLDER_LATEST_CONTENT(HST{1.2}). Your development workarea is changed each time an object is checked in. The 'other' workareas are only changed for each promotion. Each promotion results either in a additional configuration and/or a change of the workarea definition.

Note that the Oracle9i Designer security model fully supports the implementation of promotions via workareas. For example a developer may have write access on the container HST. At the same time he will probably have only read access to workarea WA_PRD_HSD and only read access to folder c:\oap\hst\prd. He or she will never be able to change the repository content in the production environment and will not be able to synchronize the file system in the production environment.

The number of configurations will grow significantly during the life time of an application. You should therefore adopt a naming standard for configurations that identifies at least the following components in the configuration name: <root container name>_<base line release nr>_(<patch release>). For example HST_505_11 represents patch 11 for base line 5.0.5 of container HST.

## Different folder mappings in the development workarea for each developer

You may skip this section if you do not (yet) want to enter the versioned world.

The above folder mappings for the development workarea should typically be defined by the project configuration manager - Chapter 7 gives a detailed description of this specific user group - who is responsible for the content of the development environment in the repository and eventually on the file system.

Developers however should not adopt this specific folder mapping for each root container in the development environment. They should adopt a private workspace for each container. These will not interfere with each other when they use a private workspace for changing the files. This private workspace can either be set locally (e.g. c:\work\hst) or on a share (e.g. f:\work\hst).

Note that the above "private" folder mapping is supported by Oracle9i Designer since the folder mapping is uniquely defined per workarea, container and workstation. The folder mapping is saved in the registry node HKEY_CURRENT_USER\Software\Oracle\FileSystem\ on each workstation.

## Remove obsolete containers and other objects

Skip this activity if you do not (yet) want to enter the versioned world

In the previous tasks you may have created the following candidate obsolete objects:

- workareas that support the migration process (e.g. WA_des6i_ora8i)
- additional application systems that captures additional object versions (e.g. HSD_TST)

The initial workareas were replaced by workareas that support the development and deployment process (e.g. WA_DEV_HSD, WA_TST_HSD).

The additional application systems (not checked in) are no longer necessary once you have built the version trees of one or more structured objects and you have verified the differences via the compare utility.

You can remove these application systems via the delete application system option (available while clicking the right mouse button). However, note that you have to follow a specific order to delete an application system effectively. For instance you cannot delete an application system that has outgoing short-cuts.

Subsequently you can remove the 'migration' workareas. Note that all objects should be either checked in or removed to successfully delete a workarea.

Note also that the Oracle9i Designer repository has adopted a wastebasket strategy. Deleted objects will appear in the wastebasket. You should subsequently empty the wastebasket to definitely remove the objects from the repository.

## Compute statistics

Now is a good time to rerun the "Compute Statistics" since your repository content is reorganized (and cleaned up). The "Compute Statistics" run will avoid a degradation in repository performance.

In Oracle9i Designer, you can run the utility directly from the Repository Administration Utility window by clicking the Compute Statistics button:

# Chapter 7 Migrate users and assign access privileges

Your Oracle9i Designer repository should by now contain different workareas, containers and sub-containers, configurations and of course structured elements and files. These objects are however not yet accessible to subordinate users. Guidelines for creating subordinate users and the distribution of the appropriate access rights on the previously mentioned objects will be discussed in this section.

The concepts "workareas", "containers" and "configurations" are new for Oracle Designer 6i/Oracle9i Designer. In addition there are new system repository access rights for subordinate repository users. Therefore users and access rights are not migrated via the migration wizard. Subordinate users can be maintained in the Repository Administration Utility.

The following subjects are covered in this chapter:

- Classification of users in user groups
- Access rights per user group per repository, workarea, container and configuration
- A description of the Oracle9i Designer repository system access rights
- Database access rights for subordinate users
- Provided migration user scripts

The system repository access rights, specific access rights to the GLOBAL_SHARED_WORKAREA and container access rights are also valid in a non-versioned world. The configuration access rights are only meaningful in a versioned world

## Classification of user groups and subsequent access rights

The table presented below combines the following dimensions:

- Configuration Management Role (e.g. Developer, DBA)
- Tasks per role - in a specific environment (e.g. development, test, production)
- Access rights per workarea, container and configuration

These user groups or roles may typically be represented in your organization to develop and deploy your (Oracle) applications. Obviously one specific user could be associated with one or more user groups. Typically you could reuse your access guidelines based on your user group classification.

Application life cycle tasks and subsequent access rights against workarea, containers and configurations

Role | Application life cycle tasks | Workarea | Container | Configuration
--- | --- | --- | --- | ---
| Development |  |  |
Security Manager | Maintain the Development environment (owner of development workarea) in the Oracle9i Designer repository - via a personal key Approve repository users in the repository database instance and send request to DBA group for user creation Create Orace9i Designer repository development users and associate system repository access rights - via a generic key (schema owner of the Oracle repository) Provides access rights - via ROB roles - to the members (e.g. PCM, Developers, DBA) of the development domain (development workarea) | SAIUDVCU (1) Owner of workarea | NA | NA
Project Configuration Manager (PCM)/ Team leader (TL) | Plan, distribute and monitor minor and major change requests Plan, distribute and monitor bug-fixes Maintain the directory structure (owner of containers in the repository) and provide access rights to all participants to the directories Prepare changes for deployment into major and minor releases (configurations) Maintain configurations (owner of configurations) and provide access rights to all participants to the configurations Define branch labels to support parallel development | SxIUDVCU | SAIUDV (2) owner of containers | SAIUDV (3) owner of configurations
Developer | Check in and check out elements and apply revision information as a result of change requests and bug fixes Perform impact analysis - for scooping purposes- leading to the additional storage of dependencies between structured elements and files Isolate elements into sets as a result of minor and major change requests and bug fixes Maintain the application database objects in the development database Maintain the application files on the development file system Maintain the dependency information Purge insignificant object versions | SxIUDVxx | SxIUDV | SxIUDV
DBA | Create repository users on request of SO and provide database system access rights in the repository database instance Create and maintain a development database instance Create application specific database administrative elements (storages, tablespaces) for the development database Prepare application specific database implementation properties (e.g. storages, tablespaces) for the development, test, acceptance and production domain Check in and check out elements in the development domain to apply specific database implementation properties Review the generated and adapted database implementation scripts (captured in configurations). The review can only result in a approval or disapproval of the entire configuration. The DBA should not modify the content of the configuration Approve or disapprove the database implementation scripts (captured in configurations) | SxIUDVxx | SxIUDV | SxIUDV
Quality Manager | Look up the repository content to monitor the usage of CM standards and guidelines | Sxxxxxxx | Sxxxxxxx | Sxxxxxxx
| Release Management Preparation Workarea(s) |  |  |
PCM/TL | Owner of the personal release management preparation workarea | SAIUDVCU (1) Owner of workarea | NA | NA
| Test |  |  |
Security Manager | Maintain the Test environment carrier (owner of test workarea) in the Oracle9i Designer repository - via a personal key Create Oracle9i Designer repository test users and associate system repository access rights - via a generic key (schema owner of the Oracle repository) Provides access rights - via ROB roles - to the members of the test domain (test workarea) | SAIUDVCU (1) Owner of workarea | NA | NA
Developer (as a tester) | Accept (or refuse) major and minor changes (packaged in releases or configurations) in the test domain Bring change requests (captured in releases) forward to the test environment Bring bug fixes (captured in releases) forward to the test environment Build the application database objects in the test database Build the application files on the test file system Verifies the repository content (what should be installed in the test domain) with the actual content on the file system and database in the test environment | SxxxxxCU | Sxxxxxxx | Sxxxxxxx
DBA | Create and maintain a test database instance Create application specific database administrative elements (storages, tablespaces) for the test database | NA | NA | NA
Application Support | Look up the content of the test domain | Sxxxxxxx | Sxxxxxxx | Sxxxxxxx
Quality Manager | Look up the repository content to monitor the usage of CM standards and guidelines | Sxxxxxxx | Sxxxxxxx | Sxxxxxxx
| Production |  |  |
Security Manager | Maintain the Production environment carrier (owner of production workarea) in the Oracle9i Designer repository - via a personal key Create Oracle9i Designer repository production users and associate system repository access rights - via a generic key (schema owner of the Oracle repository) Provides access rights - via ROB roles - to the members of the production domain (production workarea) | SAIUDVCU (1) Owner of workarea | NA | NA
Application Support | Accept (or refuse) major and minor changes (packaged in releases or configurations) in the productiont domain Bring change requests (captured in releases) forward to the production environment Build the application files on the production file system Verifies the repository content (what should be installed in the production domain) with the actual content on the file system in production environment | SxxxxxCU | Sxxxxxxx | Sxxxxxxx
DBA | Create and maintain a production database instance Create application specific database administrative elements (storages, tablespaces) for the production database Build the database objects in the production database Verify the repository content (what should be installed in the production domain) with the actual content in the production database | Sxxxxxxx | Sxxxxxxx | Sxxxxxxx
Developer | Look up the content of the production domain | Sxxxxxxx | Sxxxxxxx | Sxxxxxxx
PCM/TL | Look up the content of the production domain | Sxxxxxxx | Sxxxxxxx | Sxxxxxxx

The specific abbreviations for access rights against workareas, containers and configurations are explained in the table below. Note however that not all access rights are applicable to each of these (administrative) elements. For example "Compile" and "Update Spec" are only applicable in the context of workareas.

Table 2. Overview of access rights for workareas, folders and configurations

Access right | Meaning
--- | ---
Select | Select element(s)
Administrate | Determine access rights for other users
Insert | Insert element(s)
Update | Update element(s) and object properties
Delete | Delete element(s)
Version | Version an element
Compile | Refresh a workarea (workarea only)
Update Spec | Change workarea rules (workarea only)

Note that you should also address the roles - and their derived access rights - that are involved with maintenance of the Oracle9i Designer tool stack. The table presented below addresses these roles and subsequent tasks - without the derived access rights.

Oracle Tool stack tasks

Role | Task
--- | ---
Security Manager | Set temporary password of the Designer repository owner for DBA to apply repository patches
Quality Manager | Design and implement migration strategies Monitor the usage of Configuration Management (CM) standards and guidelines in the repository Maintain CM Handbook & Standards and guidelines Distribute CM procedures
Support maintenance | Solve notifications (from first line support) via Oracle Customer Support Notify the availability of new Maintenance releases and patches of Oracle9i Designer (client side) Forward Oracle9i Designer server patches to DBA group
First contact point | Record all issues with the usage of Oracle9i Designer (first line of support) Notify the issues to second line support
Desktop support | Distribute new Oracle9i Designer versions and patches on NT client
DBA | Distribute Oracle database software versions (base lines and patches) Create Oracle9i Designer repository database objects (base lines and patches) on the database server Tune the Oracle9i Designer repository

The access rights against workareas, containers and even configurations can be (re)defined simultaneously - via a discontinuous select - as illustrated below.

You can launch the above screen by first performing a discontinuous select of the workareas, containers and configurations , subsequently choosing the grant access rights option - available on the file menu and define the access rights for one or more users simultaneously.

Note that you have to set access rights for each root container and its sub-container(s). The container grant access rights utility therefore has an option, called Recurse Sub-Containers, to set the same access rights for all sub-containers.

Note also that the final access rights for a specific object (e.g. insert, select, delete or update of an entity, a table or a module) are determined by an evaluation of both the access rights against the workarea and the container(s). For example if an Oracle9i Designer repository user has select rights on the container HST and select, insert, update, delete and version on the WA_DEV_HSD workarea, in the end he or she can only select any object within the container HST (despite his or her extended access rights against the workarea).

## System repository access rights

The system repository access rights are significantly changed. You can define the following system repository access rights for a specific user:

Abbreviation | System Oracle9i Designer allowances
--- | ---
Management |
WA | Workareas
CFG | Configurations
CTR | Containers (Folders or application systems)
USR | Users
BRL | Branch Label
DPD | Dependencies
REG | Registration
Perform |
SPY | Set Policy
FRC | Force
PRG | Purge
GPR | Global Purge
Connection |
RON | Repository Object Navigator
RAU | Repository Administration utility
MTX | Matrix Diagrammer
RPTL | Reporting Tool
CLI | Command Line Interface
VHV | Version History Viewer
VEV | Version EventViewer
MIG | Migration wizard

Note that the following system repository access rights are applicable only in a versioned world: Containers, Users, Dependencies, Registration, Force, Repository Object Navigator, Repository Administration Utility, Matrix Diagrammer, Reporting Tool and Command Line Interface.

You could create another table that combines the above access rights and the earlier presented roles: system repository access rights per role.

## Database system privileges

Any subordinate user - no matter what repository role - needs only the following system privileges on the repository database instance:

- Create Session
- Alter Session

With the above database system privileges, any subordinate user can access all Oracle9i Designer tools and diagrammers and populate the repository with (new) elements.

## User migration scripts

Oracle9i Designer comes with two dynamic scripts that may support the user migration:

- ckgenusr.sql - This sql script creates the database user script.
- ckgenprv.sql - This sql script sets a default set of the system repository access rights per user.

You can find both scripts in the <oracle_home>\repadm61\utl directory. These scripts must be executed in the source repository database instance while the results must be executed in the target repository database instance.

It should be clear that - after execution in the target repository - you need to revise the system repository access rights for each user - depending on his or her role. Subsequently you must define the access rights per workarea, container and configurations - based upon the classification presented above. The ckgenprv.sql script does not set these latter access rights since they are new in Oracle9i Designer. Note also that both scripts may bring forward obsolete users - users that were not removed in the source repository.

# Chapter 8 Synchronize the file system and the database with the repository content

In the previous steps you have populated and reorganized the repository and you have made it accessible in a controlled way to subordinate users. A significant part of your repository content will ultimately populate your databases and file systems. This chapter will discuss the options available to synchronize the file systems and the databases with the repository content (see the illustration below). These synchronization options allow you to adopt model-based development and deployment during the complete lifecycle. You can effectively use the repository content as a reference model for all your promotion environments. You are able to rebuild your file system and database in each environment on any specific moment. Moreover you will have a variety of impact analysis tools available to solve the issues effectively in any environment since you can use any diagrammer and the dependency analyzer in the context of any workarea.

Both synchronizations will be discussed in detail in the following sections.

Effectively you can only synchronize the file system and database in the development environment (via the GLOBAL_SHARED_WORKAREA) if you have not yet entered the versioned world, because you have only one object version available.

## File system synchronization

Each promotion environment for a specific application can be represented on the file system by a specific root directory. For example the test environment for container HST can be represented by the directory f:\oap\hst\tst. At the same time the directory f:\oap\hst\prd represents the production environment of HST. This allows you to test the form HSD0002F version 2.0 without interference of version 1.0 of HSD0002f in production - captured somewhere below f:\oap\hst\prd.

The synchronization of the file system with the repository content for each promotion environment is based upon the folder mapping option.

You are able to apply a different folder mapping for each workarea. Remember that each workarea was representing a specific promotion environment. For example the folder mapping for container HST in the development environment - within workarea WA_DEV_HSD - can de defined as f:\oap\hst\dev. While the folder mapping for container HST in the test environment - within workarea WA_TST_HSD - can de defined as f:\oap\hst\tst.

Once you have established the folder mappings for each container in each workarea you can use the download option to actually synchronize the repository content with the file system. The download option extracts all files from the repository and copies these files to the file system (illustrated below).

Note that the download option not only synchronizes the current directory but also all recursive directories.

Remember that most workareas (except the development workarea) were based upon one or more configurations. Each workarea content change - as a result of configuration membership changes - should therefore be succeeded by a synchronization step on the corresponding file system to keep the repository content in sync with the file system.

### File synchronization options

Oracle9i Designer has implemented the following options to communicate with the file system and the repository in the context of files.

- Upload
- Download
- Synchronize
- Check-in

The meaning of these file options will be explained in detail in the following sections.

#### Upload

The upload option allows you to store files and/or folders in the repository from a specific operating system path - either based upon the default folder mapping or session specific value.

Note that the upload option was used during the migration to populate the repository initially with files.

#### Download

The download option allows you to publish files and/or folders from the repository from a specific folder path on the operating system in a specific operating system path - either based upon the default folder mapping or session specific value.

Note that the download option can be used to synchronize the repository content with the file system.

#### Synchronize

The synchronize option updates files in the repository with the contents of the corresponding files in a mapped file system or vice versa, depending on which is the later version.

#### Checkin

The check-in option versions the (uploaded) file, i.e. the file is already stored in the repository and in addition it will be populated with version information.

Note that the check-in action is applicable only in a versioned repository.

## Database synchronization

Each promotion environment for a specific application can (preferably) be represented via a database schema in a separate database instance. For example the database objects in the test environment for container HST in workarea WA_TST_HSD can be represented by a schema owner HST_OWNER in a specific database instance called HSTTEST. At the same time the database schema HST_OWNER in database instance HSTPROD can represent the database objects in the production environment of HST in workarea WA_PRD_HSD in another database instance. This allows you to test table HSD_PROJECTS version 2.0 in the test database instance without interference of version 1.0 of HSD_PROJECTS in production - captured in a production database instance - against the HST_OWNER schema owner.

The synchronization of the database with the repository content for each promotion environment can be implemented via the DDL generator or even the DDL generator in batch - in the context of a specific workarea. Note that the DDL generator not only generates "create database object" scripts but also reconcile scripts or "database delta scripts" if you generate against a schema that already contains all or part of the application database objects. Further note that Oracle 8i supports the "alter table drop column" statement. The database synchronization in each database instance can therefore be supported to a great extent with the DDL generators in each workarea, which makes it very attractive to adopt this promotion model.

The proposed promotion implementation model also supports the handling of database objects. For example a developer may have write access on the container HST. At the same time he will probably have only read access to workarea WA_PRD and only read access to schema HST_OWNER in the production database. He or she will therefore never be able to change the database structure in the production environment.

The above screenshot shows the DDL generator in the context of workarea WA_TST_HSD for the schema owner HST_OWNER in a test database instance - via HSTTEST connect string. Note that you can run the DDL generator for all database objects as well as for a sub-selection.

## Synchronization add-ons

Both synchronizations (repository content versus file system and repository content versus database) can be verified with the following add-ons: Keyword Expansion kit and CheckRelease.

Keyword Expansion Kit
"Keyword expansion" refers to functionality that acts upon objects that are being checked into the repository. The keyword expansion utility will look for keywords in the checked in object. Supported keywords are expanded or replaced with actual values of check-in parameters, such as author, version label, date and check-in notes. This is functionality very common to most Source Code Control tools. It allows for complete identification of files downloaded from the repository: through keyword expansion, every file can and should always contain the appropriate Version Label assigned in the repository.

CheckRelease
The CheckRelease utility comprises a GUI (Oracle Forms Module) that allows you to confront the content of one or more application systems (e.g. tables, views, files) in the context of a workarea with a build of these application systems on a file system and database. It uses therefore one or more intermediate release tables that are populated with repository information like the name, type and version number of the repository objects. This release table content represents what should be built on the file system and database in a specific environment.

Both add-ons are available via the Supplement Option. Visit www.otn.oracle.com for more information about the Supplement Option (e.g. What it is, pricing and conditions).

# Chapter 9 A typical migration plan

The previous chapters have given a technical insight in the migration efforts - represented by the blue Migration square (the task before Roll-out) in the sheet below. As you can see in the sheet below there are many more tasks to fulfill to finish an Oracle9i Designer migration project successfully. This chapter will give an overview of these other migration tasks, their characteristics and their dependencies.

The introduction of Oracle9i Designer in your organization can effectively be organized via the following phases:

- Preparation
- Trial migration
- Hardware and software upgrades Win32 clients
- Hardware and software upgrades DBMS server
- Hardware and software upgrades middle-tier
- Redesign Configuration Management (CM) tasks and responsibilities
- Redesign CM procedures and standards & guidelines
- CM and Oracle9i Designer training
- Migration
- Rollout

## Preparation

The preparation stage should deliver your migration plan. Such a plan should cover the following decisions:

- Big bang migration of structured elements or a stepwise migration
- Bring in files in the repository as well?
- Introduction Oracle8i/ Oracle9i functionality
- Migration strategy for database objects, Oracle Developer components and Web PL/SQL modules as described in Parts 3, 4 and 5
- Migration or implementation of business rules
- Scope of migration in the Configuration Management area
- Redistribution of tasks as a result of a different way and writing method

It should also comprise:

- Opportunities, Objectives & Scope
- A detailed task overview with resource usages
- Project organization
- Costs and benefits

Note that a detailed task overview can be based on the overall tasks presented above.

## Trial migration

A trial migration can be planned on separate hardware platforms - client, middletier and server - to evaluate the repository size and performance aspects. In addition you can reuse the trial migration environment for educational purposes, to develop your set of configuration management procedures and standards & guidelines, and it can provide effective output for the subsequent hardware and software installation tasks on the client, middle-tier and server platforms.

## Hardware and software upgrades Win32 clients

Your current clients (Windows 98/NT/2000/XP) may not be sufficient in terms of disk space, processing capacity and memory to run the Oracle9i Designer software and subsequent components like Developer. A hardware and software upgrade may take some time, specifically if you have a significant number of win32 clients. In addition you can prepare the automation of the software distribution of the Oracle9i Designer tool stack via for example the Novell Application Launcher or other client distribution tools like SMS.

## Hardware and software upgrades - DBMS server

The hardware and software upgrade of the database server covers - at least - the database instance for the Oracle9i Designer repository. It could also cover the upgrade of the databases that capture your applications.

Oracle9i Designer is certified with 81700 or higher and Oracle9i patched to 9.0.1.2. Note that a database upgrade can also implicate an upgrade of the operating system. Therefore not only the DBA department but also the department that manages server platforms must be involved.

## Hardware and software upgrades - middle-tier

Oracle9i Forms and Oracle9i Reports - part of the Oracle Internet Development Suite (iDS) - do not support a client/server architecture. It is therefore highly recommended that you introduce or update your middle-tier platform with new software components - or an upgrade - to Oracle 9iAS. In addition to hardware upgrade issues, it may also involve a new version of the underlying operating system. In addition - specifically if you introduce a middle-tier - you must deal with management (support) and knowledge transfer of the middle-tier software. In practice, this stage and the organizational impact proves to be the most underestimated.

## Redesign Configuration Management (CM) tasks and responsibilities

The introduction of Oracle9i Designer and the underlying repository brings along a new writing and working method for a wide range of participants, since the repository will be used for development as well as deployment. Your big challenge is to cover all the tasks (see also the matrices for application life cycle tasks and tool stack maintenance tasks presented in Chapter 7 "Migrate users and assign access rights") in your specific organization. This stage is perhaps the most challenging one of your entire migration project - so do not underestimate it.

## Redesign Configuration Management procedures and standards & guidelines

As soon as the redistribution of tasks and responsibilities is well under way you can start with the production of the redesign of configuration management (CM) procedures and standards & guidelines.

You could try to produce a big fat configuration management handbook - that most likely at the end of the day will only be consulted by you. You could also try to adopt a less is more approach, i.e. produce multiple Quick Reference Cards that cover for example your CM procedures, CM Standards & Guidelines and tool support. You could think of Quick Reference Cards candidates:

- Repository Terminology
- Check-in and Check-out Quick Reference Card
- Overview of Designer/Repository Tools
- Naming Standards (workareas, configurations, ddl scripts)
- Database synchronization and DDL generation guidelines
- Guidelines for the use of the Database Design Transformer
- Management of Repository Access rights
- Setup of a parallel environment
- Setup of a bug-fix environment

A few examples of the above listed Quick Reference Cards are presented in Appendix B.

## Configuration Management and Oracle9i Designer training

An effective and productive migration and subsequently the effective usage of the Oracle9i Designer tool stack and subsequent CM procedures relies heavily on well trained participants. By now it should be clear that not only developers need training but also other participants, such as project configuration managers, application support representatives and the security department that provides access to the repository.

An effective CM and Oracle9i Designer training plan therefore should be based on the profiles or roles as covered in the matrices presented earlier. Therefore you cannot start the training task before the first results of the redistribution task are available. Subsequently you should evaluate for each profile the need to cover one or more of the following training subjects:

- Oracle9i Designer new database features
- Oracle9i Designer Forms and Reports generation new features
- Oracle9i Designer WEB PL/SQL modules new features
- Oracle9i Designer new Configuration Management features
- Business Rule implementation via CDMRule Frame
- Oracle9i Designer Forms and Reports generation via Headstart
- Knowlegde transfer of one or more custom Configuration Management procedures - perhaps captured in the Quick Reference Cards
- Subsequently you can fill in the identified training needs per profile with a combination of standard available courses and/or custom courses.

## Migration

The technical migration aspects are already discussed in detail in the previous chapters of this part (Part 2). In addition more specific migration details on an object-type-by-object-type basis will be provided in Parts 3, 4 and 5. The migration task can only start - as will be pointed out below - with skilled developers. Your migration start date is therefore not only dependent of the hardware/software availability, but also on a skilled staff that can perform one or migration activities.

The coherence between these different migration steps of structured elements and files in the different source repositories and Oracle9i Designer repository and the inevitable parallel development as a result of these migration steps can be visualized as follows:

From top to bottom the following repositories are depicted:

- PVCS/VM source repository for files - could also be another third party source control
- Designer 1.3.2 repository - source repository
- Designer 6.0 repository - intermediate repository
- Oracle9i Designer repository - target repository

From left to right a time period is depicted - somewhere between 1 week and 3 months depending on the size, number and complexity of the application systems and/or projects and not in the least on the specific migration scenarios for the specific object types - as discussed in Parts 3, 4 and 5.

To explain the parallel development challenge you should start at the lower left corner in the Designer 1.3.2 repository and the third party repository (e.g. PVCS/VM repository) with a clean-up (depicted by the purple arrows).

Parallel with the clean-up stage you can start with a fresh installation of Designer 6.0 - to capture intermediate application systems - and Oracle9i Designer - to capture the target application systems and files (depicted by the dark green arrows). If your application systems already live in Designer 6.0 you should replace all references to Designer 1.3.2 with Designer 6.0 and you can skip the fresh installation of Designer 6.0. After the clean-up you export a coherent set of application systems into the intermediate Designer 6.0 repository (depicted by the lower vertical red arrow). At the same time you import this set back in the Designer 1.3.2 repository under different application names. This set will be used as a snapshot of your migration start.

Developers can continue with their work in Designer 1.3.2 although you should not encourage them to apply a lot of changes, since these changes are by definition not captured in the imported set. In the intermediate Designer 6.0 repository, clean-up activities like re-connect share links can be picked up (depicted by the upper purple arrow). As soon as these clean-up activities are finished you can launch the migration wizard in Oracle9i Designer, connect to the Designer 6.0 repository and make the selection (depicted by the upper vertical red arrow). The migration wizard will bring the application set forward in the Oracle9i Designer repository. Subsequently you can freeze the application systems in Designer 6.0 (depicted by the yellow arrow) and start with a check-in of the structured elements in Oracle9i Designer - to capture the fresh migration result (depicted by the light green arrows). You could also leave them un-versioned and apply your migration scenarios for database objects as described in Part 3.

While one or more of your developers is executing the database migration scenario you can start with the upload of files on a project-by-project basis from the PVCS/VM repository as described in Chapter 4 (depicted by the right upper - solid and dotted - vertical red arrows). You can close down each PVCS/VM project as soon as the files are uploaded in the Oracle9i Designer repository (depicted by the dotted yellow arrows). The parallel development time for files can be very short - less than a day - since you do not have to verify the generation capability as with structured elements.

While the files from one or more PVCS/VM projects (or file system) are uploaded you should focus on finishing the migration steps for database objects as described in Chapters 3 and 4 of Part 3 (depicted by the right light green arrow - verify database objects). By now you should have reached the reorganization phase in your target Oracle9i Designer repository. In this phase you will organize your repository in one or more development workareas - containing the migrated application systems and files - and you will bring forward your subordinate users with the appropriate access rights, see also Chapter 7 (depicted by the right light green arrow). With more subordinate users - developers - you can start effectively with the migration scenarios for Development components and WEB PL/SQL modules as described in Parts 4 and 5. In addition you may want to apply one of the database new features migration steps as described in Chapter 5 of Part 3 (depicted by the brown arrow).

While applying these migration steps in the target repository you will also bring forward all the changes from the source repository since the start of the migration. You could use the snapshot very effectively to narrow down the exact changes since the start of the migration. As soon as you have brought forward the source repository changes - manually - in the target repository you can close down the source repository application system (depicted by the dotted blue arrow). The real challenge here is to close down the source repository application systems as quickly as possible or to phrase it differently to minimize the parallel development period. Note that you must bring forward more changes with a longer parallel development period. You can accomplish a short period by basically bringing in as much qualified resources as you can to execute the migration scenarios of Parts 3, 4 and 5.

## Rollout

Finally - after finishing the migration of structured elements and files as described in Part 2 and after finishing the migration scenarios of Parts 3, 4 and 5 - you can roll out Oracle9i Designer to all participants that are involved in development and deployment. Basically you are offering on-site support during first time Oracle9i Designer use by all participants during this phase. The support activities must elaborate on the training effort. They should definitely not replace the training courses. It turns out that the acceptance and effective usage of Oracle9i Designer will speed up significantly if you can find enthusiastic and skilled representatives in each department. These early adopters in each department can soon take over the support task and take care of wide effective usage of the Oracle9i Designer tool.

Prev | Next
| Copyright © 2002, Oracle Corporation. All Rights Reserved. |
Contents