Oracle9i Designer Migration Guide Appendix B. Quick reference information |
Contents

# Repository Terminology quick reference information

## Application (Container)

A type of Container that groups Structured Elements with a logical affinity to each other. This affinity may be data related (that is, all data elements for <App System Cluster>) or function related. An Application may container Folders to hold related File Elements and Documents (that is, ins and ddl).

## Application Item

A type of Configuration Item that is the direct source for an application executable element (that is, Module Definition, Report Source File). These generate out as Developer, PL/SQL, etc. source or are extracted “as is”.

## Application System Cluster

A group of application systems that are strongly interrelated. For example a set of entities and tables from application system CORE is referenced by the application systems SALES and STOCK. You would typically group these application systems in a single workarea.

## Base line configuration or release

A base line configuration - or base line release - represents a full set of object definitions for a specific system. For example base line configuration <App System> 3 represents release 3 of system <App System> and contains all elements within <App System> that should be deployed for release 3.

## Branch

Branches are sequences of object versions that have their starting point at a particular version in an existing branch, but evolve independently. All the versions together create a version tree. A version tree always has a MAIN branch, and may also have sub-branches. Branching enables you to develop multiple versions of a product simultaneously (parallel development) using the same set of source files.

When you check in an object for the first time, it is always added to the default MAIN branch. If the repository policy specifies an alternative branch to check in to for the first time, two versions are created, one on MAIN and the other on the specified alternative branch.

## Checkin

The checkin option versions an uploaded file/folder or a saved structured element. For example, the file or folder is already stored in the repository and in addition it will be enhanced with version information and you will be able to view the file/folder/structured element in another workarea. Note that another version of an element can only be created via a checkin operation.

## Checkout

Repository elements can be manipulated only when they are checked out (or unversioned). You therefore first have to check out a checked in element before you can apply changes. The checkout action starts with the creation of a duplicate of the element. This allows you to perform an undo checkout operation. As a result you will fall back on the original, checked in element version.

## Configuration

A configuration is another means to isolate only one version of one or more repository elements. The content of a configuration is fully static, in contrast to workareas. Like any other element you can version configuration. This version capability of configurations can be used to associate configurations with a workarea or, to put it differently, to base a workarea on one or more configurations. Another application of the configuration version capability is the storage of an original element set in the “first” version of the configuration. Within the next version all corresponding derived elements (ddl files) are stored.

## Configuration Item

The product of a task, or a deliverable for the project, which is placed under Configuration Management.

## Container

A grouping of items for the purpose of usage, access, or extraction. Within the Oracle Repository containers can be Applications (for example, DMO, Headstart) or Folders (for example, ins, ddl). Containers should not be confused with Workareas (see below). Workareas are a means of presenting containers and their contents.

## Data Content Item

A type of Configuration Item that is the direct source for the initiation of a database schema element (that is, seed data script). These are extracted “as is” for use.

## Data Management Item

A type of Configuration Item that is the direct source for the restructuring, conversion, or initiation of a database schema element (that is, restructure table script). These are extracted “as is” for use.

## Data Structure Item

A type of Configuration Item that is the direct source for a database schema element or a database schema logic element (that is, Table or View Definition). These generate out as DDL scripts.

## Database Schema

A database schema is a user in the database. Each database element like a table or view (expect a role) is owned by a database schema.

## Database Synchronization

Database Synchronization refers to the state of database definitions in the repository versus its mapped database objects in the database within a database schema. There can be a mismatch between these two, since there are (within the context of a workarea) two database representations, one in the repository and one in the database. The database synchronization status can be checked with the CheckRelease Form (see CheckRelease QRC).

## Database User

See database schema. Note that each database user can access its own database objects - obviously. In addition a database user can access database elements of other users - or schema’s - via a mechanism of grants and synonyms.

## Document (Item)

Any type of Configuration Item which is part of the supporting description an application system’s architecture, environment, usage, or its general definition.

## Download

The download option allows you to publish files and/or folders from the repository to a specific folder path on the operating system - either based on the default folder mapping or session specific value. The download will prompt you if the file already exists on the file system.

## Edit Workarea Rule Specification

The content of a workarea is primarily determined by workarea rules (see above). You need a specific workarea access right (Update Spec) to change the workarea rules for a workarea. This Update Spec policy is given only to a PCM. This Update Spec right must be distributed in combination with the Refresh or Compile right (see below).

## Element

Any type of Configuration Item (see above), intermediate item (not under configuration control), executable item (for deployment), or other component which is associated with the development and deployment of the application system that is being constructed or maintained. An element can be either structured or unstructured (file).

## Environment

A specific set of elements drawn from across each of the technology layers. An environment is identified as being for a particular promotion state or purpose, such as application development or application deployment. An environment will include a specific Baseline Configuration, a directory structure containing source and executable programs, a specific database schema containing data structures and data content, and an accessible toolset.

## File Element

A type of Application Element which may or may not have been originally sourced from Designer, but whose current source is the file system representation, (for example, a report with post-generation changes, or data conversion scripts written by hand).

## File Synchronization

File Synchronization (not to be confused with the synchronization option, see above) refers to the state of files in the repository versus its mapped files on the file system. There can be a mismatch between these two, since there are (within the context of a workarea) two file representations, one in the repository and one on the file system. The file synchronization status can be checked with the CheckRelease Form (see CheckRelease QRC).

## Folder (Container)

A type of Container that groups File Elements with a logical affinity to each other. They may be related by usage, project phase focus, or other criteria. Top level Folders are usually created as children of Applications and may contain other Folders in turn. A standard set of Folders has been identified for general use in all Applications (that is, ins and ddl).

## Folder Mapping

Folders - containers for files - in the repository can be mapped against directories on the file system via the folder mapping option (available for root containers only). This mapping - stored locally in the registry - is reused while downloading and uploading files (see below).

## Item

See Configuration Item.

## Item Type

The classification of an Item based on its definition, characteristics, or use (see below).

## (CM) Repository

A storage system which contains a copy of all the items under Configuration Management control, and also contains the information that relates those items to each other and to project deliverables. This facility is provided by the Oracle Repository, which is implemented as a specific database schema, that underlies the Oracle Designer toolset. The CM repository contains for example all <App System> entities, tables, views and files and subsequent versions.

## Root Container

A root container (application system or folder) is the starting point of a container structure like a root directory on the file system.

## Partial configuration

A partial configuration contains only a limited set of object definitions for a specific release. A partial configuration can be associated with a single registered enhancement request (“Change Request”) or with a bundle of registered enhancement requests. For example partial configuration <App System>_20013011 represents enhancement request <App System>_20013011 for system <App System> and contains only objects that are associated with this enhancement request.

## Refresh a Workarea

The refresh or compile option of a workarea (another specific workarea access right) reevaluates the content of a workarea based upon the workarea rules, without changing the workarea rules themselves. The end-result (pointers) is stored in the workarea table.

## Requery a workarea

The requery does not reevaluate the workarea rules, but takes the persistent workarea table content as a given and requeries all primary and secondary elements, associations and properties.

## Sandbox Workarea

A sandbox - or playground - workarea can be used for the preparation of releases or to experiment with workarea rules. The use of a separate workarea during the preparation of a release circumvents the interference with ongoing development and testing activities.

## Specific Workarea Operations

The following operations can be executed against a workarea:

- Change the workarea rules or edit workarea rule specification.
- Refresh a workarea.
- Requery a workarea.

## Structured Element

A type of Application Element that is defined wholly within the Designer toolset and is then generated out from there for use in the application system (that is, Entity, Table Definitions, View Definitions)

## Synchronization

The synchronization option (files only) compares the repository content with the underlying file system, for a specific directory tree. Subsequently it will suggest uploads and downloads for file mismatches. This option will however be rarely used because files are downloaded or uploaded on a individual basis during checkin and checkout procedures (see Checkin and Checkout QRC).

## Target or destination file system

The target or destination file system is the environment on the file system level that will receive the files for a specific system (DMO) captured in a specific release.

## Target or destination database schema

The target or destination database schema is the schema in the database (in the specific target database instance) that captures the database objects of one or more systems (for example, <App System>, OHL) of a specific release (or configuration).

## Target or destination workarea

The target or destination workarea is the environment in the repository that will receive the release, captured in a configuration. The target or destination workarea, given the (D)TAP model, could be Test (for example, <App System>_TST_REL<release nr>), Acceptance test (for example, <App System>_ACC) or Production workarea (<App System>_PRD).

## Tip Version

The latest object version of a branch.

## Upload

The upload option allows you to store files and/or folders in the repository from a specific file system path, either based on the default folder mapping or session specific value. Note that an upload does not check in the element. That is, no version properties are added and you cannot view a stored file/folder in another workarea.

## Verification of the Synchronization between the Repository versus File and Database

The CheckRelease Form reports about the synchronization status of repository elements versus its file representatives on the file system and its database representatives in the database (see also CheckRelease QRC).

## Version

The rendering of an item which incorporates all of its revised content starting from a given point (that is, from a previous version).

## Workarea

A workarea serves as an access vehicle or environment to the repository content. Within a workarea you can see (and manipulate with appropriate access rights) only one version of one or more objects, grouped in a container structure. A workarea therefore provides a version resolved access mechanism to the repository elements. A workarea only contains pointers to the full definition of the element - it does not capture the full element definition.

The content of a workarea can change over time, for example via checkin and checkout actions. That is, a workarea content is dynamic. Almost all Oracle SCM and Oracle Designer tools (except the repository object navigator) - allow you to access the repository elements only in the context of a workarea. That is, you cannot access the Design Editor in the context of a configuration.

Note that there is, luckily, no need to version a workarea. You cannot therefore version a workarea.

## Workarea rules

The content of a workarea is primarily determined by workarea rules. A workarea can contain multiple workarea rules (for example, LATEST(MAIN), INCLUDE_FOLDER(<App System>)) that are evaluated one by one (from top to bottom). The evaluation result (pointers to the full element definition) is subsequently stored in a persistent way (in a workarea table).

# Designer/Repository Tools Quick Reference Information

## Repository Object Navigator (RON)

The RON or Repository Object Navigator provides a tree-navigational interface to the repository elements (structured elements and files). Subsequently the RON hosts all configuration management functionality like the manipulation of workareas, configurations and branches, file manipulation, and merge utilities.

## Design Editor (DE)

The DE or Design Editor also provides a tree-navigational interface and a graphical interface to the structured design repository elements like tables, views and sequences. In addition, it hosts the DDL generators. Note that these generators are no longer available in the RON.

## Version History Viewer (VHV)

The Version History Viewer displays a graphical interface of all versions of a specific element. You can launch the VHV from the RON or DE.

## Version Event Viewer (VEV)

The Version Event Viewer displays a character-based interface of all versions' history information (for example, checkin/checkout notes, the owner of the changes, when changes took place) of a specific element. You can launch the VEV from the RON or DE.

## Element Compare Tool

The element compare tool displays a detailed overview of the differences between two element versions. You can launch the element compare tool either from the RON or DE.

## Element set compare tool

The element set compare tool displays an overview of the element set differences, differences in version numbers, for example the differences in element set memberships of two workareas or configurations.

You can launch the element set compare tool only from the RON.

## Element merge tool

The element merge tool merges differences between two object versions on different branches on a conflict by conflict basis. For example you can merge object version 1.2.1.1 into MAIN branch label 1.4 resulting in version 1.5.

You can launch the merge tool from the VHV.

## Merge Wizard

The merge wizard allows you to perform a merge for a set of elements.

For example you can merge all elements checked in on a specific branch (for example, <App System>_REL1) into the corresponding elements in the workarea that captures the MAIN branch (for example, <App System Cluster>_DEV).

You can launch the merge wizard from the RON.

# Naming Standards quick reference information

## Release nr [x]

For example, 10.

The format of a release nr is indicated with x where x represents the major component. A release can contain all objects of an application system (baseline release) or it can contain only the changed and added objects introduced in a specific release (increment). Note that releases are implemented by configurations and that you could have multiple versions of configurations (see below).

## Version nr [1.y]

For example, 1.1

The format of the version number of a single object is indicated with 1.y where y represents any major or minor change.

## Branch Version nr [1.y.1.z]

For example, 1.1.1.1

The format of a branch version number of a single object is indicated with 1.y.1.z where ‘y’ and ‘z’ represent any major or minor change.

## <App System Cluster>_DEV workarea

Workarea that captures the latest versions of all objects of one or more strongly interrelated application systems, for example MARKETING_DEV. The default checkin branch is equal to MAIN.

## <App System Cluster>_SB<sequence nr>

Workarea to prepare a specific release or to try out different workarea rules with a stack of configurations. SB stands for sand box (play ground). There is no default checkin branch and there are no database schemas associated with this workarea.

## <App System Cluster>_ACC

Workarea that captures one or more application systems of a specific release and/or application system patches that has reached the acceptance test status. There is no default checkin branch (by definition).

## <App System Cluster>_PRD

Workarea that captures one or more application systems of a specific release (and/or application system patches) that has reached the production status. There is no default checkin branch (by definition).

## <App System Cluster>_PRDFIX

Workarea that fixes incidents on one or more <App System> release that has reached the production status. The default checkin branch is equal to <App System>_REL_<release nr>.

## MAIN Branch

Branch label for the MAIN branch

## <App System>_REL<release nr> Branch

Branch label that captures the latest version of a specific <App System > release (for example <App System Cluster>_REL10).

## <App System>_PRDFIX_REL<release nr> Branch

Branch label that captures the latest version of all production fixes of a specific <App System > release (for example <App System >_PRDFIX_REL10).

## <App System>_REL<release nr> Configuration

Base line configuration for <App System> that contains a full set of all database elements or all changed and introduced elements (increment) (for example <App System>_REL10).

Note that you have to create a new baseline release if you remove elements from the <App System>.

## <App System>_REL<release nr>FIX<sequence nr> Configuration

Patch configuration for <App System> that contains all elements that are solved for one or more fixes in the context of a specific release (for example <App System >_REL10FIX1).

## <App System>REL<release nr>.<ext> DDL script

Baseline DDL scripts belonging to a specific release of an application (for example <App System>REL10.sql, <App System>REL10.tab).

For a list of possible values of the <ext> see below.

## <App System>REL<release nr>.sql DDL script

Overall DDL script, derived from the generated baseline scripts for a specific application system. The <release> part stands for the target release.

## <App System><short name table>.ins Seed data script

Seed data script for a specific table within a specific application system.

## <App System>REL<release nr>FIX<sequence nr>.sql DDL script

Overall DDL script, derived from the generated delta script(s), for a specific fix (or fixes) in the context of a specific release. <App System>REL10FIX1.sql

## <App System>_OWNER Database Schema

Specific database schema that captures the database objects of a specific application system.

## ins Folder

Sub-Folder that captures the database install (DDL) scripts.

## ddl Folder

Sub-Folder that captures the packages stored as files (for example *.pck) and the overall release delta script that is transferred to Application Services.

## <SID Name> Database Instance

System Identifier (SID) of the Oracle database.

# Checkin and Checkout Quick Reference Information

## Guidelines for Checkout and Checkin notes

1. Always fill in the checkout and checkin text box in English.
2. Provide references, when applicable, to the corresponding “Change Request” numbers.
3. Reuse the checkout text while checking in and subsequently update the checkin text with actual revision information.
4. Never perform an undo checkout against containers (application systems or folders) because you are not in control of the checkout context, other developers may have added or removed elements.
5. The context of a checkin should be equal to the change request context. That is, do not leave the element in a checked out status after you have finished your “Change Request” changes for a specific element.
6. Always add the revision keyword string to the structured design element of file (see Revision keyword guidelines).
7. Check in an element only if the element is complete and if the generated DDL syntax can be compiled or created without any errors. A table is complete if it contains all secondary elements (for example, columns, constraints, triggers, synonyms).

## Checkout checklist for existing structured elements and files

1. Consult the members of the partial configuration - representing the “Change Request”.
2. Verify the checked-in status of the element - for structured elements and files only. Consult section Request Check-list for a checked-in status of a checked-out element if the element is already checked-out.
3. Verify the appropriate version level on the branch - via the VHV. In most cases you would like to check-out the tip version.
4. Request for a refresh or recompile of the context workarea - ask the PCM) if you do not view the tip (or latest) version on the branch..
5. Verify the correctness of the folder mapping against the root-container (files only). Note that folder mapping of a root container is unique within the context of a workarea. Your folder mapping for the root container should be mapped to a private workspace on the file system (for example g:\ work\bck)
6. Check-out the specific element - either in the RON or DE - and provide check-out notes, see also section Guidelines for Check-out and Check-in notes - above. Note that you can only use the RON to check-out files
7. Check-out associated elements that also need to be modified, for example the entity at the other end of the relation.

## Checkin checklist for folders, structured elements or files

1. Check out the owning container, if the owning container is not already checked out, for new elements only.
2. Add the revision keyword string, for new elements only (see Revision keyword guidelines).
3. Check the access rights, for new folders only. Note that only a PCM is allowed to create folders.
4. Create your new file with content (files only) on the file system before a checkin.
5. Check the completeness of the elements (for example, attributes, unique identifiers, columns, constraints).
6. Check in the element and provide checkin notes (see "Guidelines for checkout and checkin notes", above). Subsequently consult that information if you need to merge the structured element or file, for non-containers elements only . Or consult "Merge guidelines for containers" if you need to merge the container, for containers only.
   Note that you can only use the RON to check in files and/or containers.
7. Synchronize the corresponding database schema via the DDL generator, for tables, views and secondary database elements only (that is, triggers, indexes) (see also Database synchronization QRC).
8. Update and check in the partial configuration by adding specific versions of the new structured elements/files or changed versions of already populated structured elements. Note that you should always include the owning container of the element.
9. Analyze dependencies with the Dependency Manager. Note that the Dependency Manager is only applicable for design objects like tables, views and seed data scripts.

## Request checklist for a checked in status of a checked out element

1. Determine the owner of the checked out element (for structured elements and files only) via the VEV.
2. Do ONE of the following:

- Postpone your changes until a checked in status is reached by the owner of the checkout.
- Request a checked in status, on the default checkin branch, of the element in the near future. This is likely to happen if the owner is nearly finished or can postpone his or her changes. Note that you may deal (and therefore agree) with an undefined status of the element if the owner was not finished yet.
- Request for a checked in status on another branch if the owner agrees that his or her changes must be merged eventually on the default checked in branch.
- Ask permission of the PCM to undo the checkout of the element if the owner is not available. Note that with this operation all ongoing changes are lost.
- Enforce a checkin on the default checkin branch thereby accepting an undefined status of the element, if the owner is (still) not available.
- Enforce a checkin on another branch (after consulting the PCM) if the owner is (still) not available.

Note that the above operations cannot be enforced by Oracle9i Designer. Every developer is able to execute each of the listed actions, since every developer has the version right and they all share the same workarea.

## Revision keyword guidelines

The repository supports the following revision keywords:

- $Re’||’vision:::xxxxxxxxxxx$ (aka revision)
- $Au’||’thor::xxxxxxxxxxxxxxxxx$
- $Da’||’te::xxxxxxxxxxxxxxxxxx$
- $Wo’||’rkfile::xxxxxxxxxxxxxxxxxxxxx$

Note that you should not use the string ‘||’ on the specific location. This string is added here to circumvent the expansion when this specific QRC document is checked in to the repository.

You should always add the “revision” keyword string, on a specific location/property, into new design elements and files. Use the following overview for the specific location:

- Table - comment property
- View - comment property
- File - in the header, prefixed with a comment tokens when used in a SQL script or Shell script

Note that you can copy/paste an existing revision keyword string for the exact syntax from existing tables/views/files. The version string is automatically updated after the checkin operation.

## Removal checklist for folders, structured elements or files

1. Verify the checkin status of the structured element, file or folders. Only checked in elements may be removed.
2. Verify the dependencies, usages and inclusions (via the RON and the dependency analyzer) of the element.
3. Determine the appropriate delete order based on your dependency investigation.
4. Check out the owning the container with checkout notes, if not already checked out.
5. Remove the element(s).

## Merge guidelines for structured elements and files

1. Perform a merge to the MAIN branch each time you are planning to cut a new release from MAIN.
2. Find the candidate merge elements, for a specific user, on a specific branch via the ROB search utility by providing a value for the following fields - on the several search ROB TABS for example:

   Workarea: [Basic]

   Branch Label : [Version]

   Checked In By: [Version]

   Check State: “Checked in” [Version].

   Note that you may find too many merge candidates, since you do not need to merge if the tip of the branch is already merged into the MAIN branch. The latter can be visualized via the ROB Version History Viewer. You could also try to narrow down the search result by translating the “merge of the tip version into the MAIN branch” condition into an “additional where clause” field on the [Advanced] search TAB.

3. Highlight the TARGET workarea where you will execute the merge.
4. Highlight the candidate merge object, check it out and launch the VHV.
5. Abandon the merge whenever the source or the target tip version is already checked out, indicated by the blue color, and start a request for a checked in status (see "Request checklist for a checked in status of a checked out element") to enforce a checkin status.
6. Mark within the VHV the checked out version, move your cursor to the source object version and launch the option “merge to mark”. The Merge dialogue or wizard tries to suggest a default change on a specific branch for every conflict. This default is indicated with an enabling of a specific version. Subsequently you can perform an automatic merge if every conflict (or difference) is associated with a default. Therefore you may have to manually interfere whenever the wizard cannot make a specific choice for a particular difference.
7. Save the merge operation. The merge itself does not automatically create a new version.
8. Verify the merge result with a compare of the source object version with the target (merged) object version and make additional changes if necessary.
9. Check in the target (merged) object version.
10. Consider a merge to other branches of the object.

## Merge guidelines for containers

The merge steps for containers are more or less equal to the merge guidelines of structured elements and files.

However, you will only be confronted with differences of folder memberships (see step 6 of the "Merge guidelines for structured elements and files").

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