Oracle Designer 6i 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 (i.e. all data elements for <App System Cluster>) or function related.  An Application may container Folders to hold related File Elements and Documents (i.e. ins and ddl).

Application Item 

A type of Configuration Item that is the direct source for an application executable element (i.e. 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.

Check-in

The check-in 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 check-in operation.

Check-out

Repository elements can only be manipulated when they are checked-out (or un-versioned). You therefore first have to check-out a checked-in element before you can apply changes. The check-out action starts with the creation of a duplicate of the element. This allows you to perform an undo check-out 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 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 (e.g. DMO, Headstart) or Folders (e.g. ins, ddl).  Containers should not be confused with Workareas - see below. Workareas are a mean 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 (i.e. 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 (i.e. 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 (i.e. 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

The Database synchronization term refers to 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 exist 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 only given 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 either be 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.  (i.e. Report with post-generation changes, data conversion scripts written by hand)

File Synchronization

The File synchronization term  (not to confuse with the synchronization option  - see above) refers to 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.  This may 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 (i.e. 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 wokarea accces right- reevaluates the content of a workarea based upon the workarea rules - without changing the workarea rules itself. The end-result (pointers) is stores in the workarea table.

Re-query a workarea

The re-query does not reevaluate the workarea rules, but takes the persistent workarea table content as a given and re-queries 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 usage 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
• Re-query a workarea

Structured Element  

A type of Application Element which is defined wholly within the Designer toolset and is then generated out from there for use in the application system (i.e. 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 download for file mismatches. This option will be however rarely used since a files are downloaded or uploaded on a individual basis during check-in and check-out procedures - see  Check-in and Check-out 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 (e.g. <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 either Test (e.g. <App System>_TST_REL<release nr>), Acceptance test (e.g. <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, i.e., 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 (i.e. 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.
It 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 check-in and check-out actions. I.e. a workarea content is dynamic.
Almost all Repository and Designer tools - except the RON - only allows you to access the repository elements in the context of a workarea, i.e., you cannot access the DE in the context of a configuration. 

Note that there is - luckily -  no need to version a workarea. Therefore you cannot version  a workarea.

Workarea rules

The content of a workarea is primarily determined by workarea rules. A workarea can contain multiple workarea rules (e.g. 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 of 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 (e.g. check-in/check-out 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  versions 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 nerge tool merge 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 (e.g. <App System>_REL1) into the corresponding elements in the workarea that captures the MAIN branch (e.g. <App System Cluster>_DEV)
You can launch the merge wizard from the RON.

Naming Standards quick reference information

Release nr [x]

The format of a  release nr is indicated with x where x the major component represents.
A release can contain all objects of an application system  (baseline release) or it could contain only the changed and added objects introduced in a specific release (increment).

E.g. 10.
Note that releases are implemented by configurations and that you could have multiple versions of configurations - see also below.

Version nr [1.y]

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

e.g. 1.1

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

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

<App System Cluster>_DEV workarea

Workarea that captures the latest versions of all objects of the one or more strongly interrelated application systems, e.g. MARKETING_DEV. The default check-in 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 check-in branch and there are no database schema’s 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 check-in 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 check-in 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 check-in 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 (e.g. <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 (e.g. <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)
(e.g. <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
(e.g. <App System >_REL10FIX1)

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

Baseline DDL scripts belonging to a specific release of an application
(e.g. <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 (e.g. *.pck) and the overall release delta script that is transferred to Application Services

<SID Name> Database Instance

System Identifier (SID) of the Oracle database

Check-in and Check-out quick reference information

Guidelines for Check-out and Check-in notes

1. Always fill-in the check-out and check-in text box in English
2. Provide references - when applicable - to the corresponding “Change Request” numbers.
3. Reuse the check-out text while checking-in and subsequently update the check-in text with actual revision information
4. Never perform an undo check-out against containers (application systems or folders) because you are not in control of the check-out context - other developers may have added or removed elements.
5. The context of a check-in should be equal to the change request context. I.e. 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 section Revision keyword guidelines
7. Only check-in an element if the element is complete, ie., a table is complete if it contains all secondary elements (e.g. columns, constraints, triggers, synonyms) and if the - generated - DDL syntax can compiled or created without any errors.

Check-out Check-list of 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 (e.g. 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, e.g. the entity at the other end of the relation.

Check-in Check-list of 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 element only. Consult section 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 check-in
5. Check the completeness of the elements (e.g. attributes, unique identifiers, columns, constraints)
6. Check-in the element and provide check-in notes see section Guidelines for Check-out and Check-in notes - above. Subsequently consult section if you need to merge the structured element or file - for non-containers elements only . Or consult section 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 (i.e. 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 DM is only applicable for design objects like tables,  views, seed data scripts, etc.

Request Check-list 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. Postpone  your changes until a checked-in status is reached by the owner of the check-out. OR
3. Request for a checked-in status - on the default check-in branch - of the element in the near future. This is likely to happen if the owner is nearly finished or can postpone his/her changes. Note that you may deal (and therefore agree) with an undefined  status of the element if the owner was not finished yet. OR
4. Request for a checked-in status on another branch if the owner agrees that his/her changes must be merged eventually on the default checked-in branch. OR
5. Ask permission of the PCM to undo the check-out of the element if the owner is not available. Note that with this operation all ongoing changes are lost. OR
6. Enforce a check-in on the default check-in branch and thereby accepting an undefined status of the element - if the owner is (still) not available. OR
7. Enforce a check-in on another branch (after consulting the PCM) if the owner is (still) not available.

Note that above operations cannot be enforced by Designer 6i. 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 in 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 check-in operation.

Removal Check-list of folders, structured elements or files

1. Verify the check-in status of the structured element, file or folders. Only checked-in elements may be removed
2. Verify the dependencies - Via the RON - usages and inclusions - 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 check-out 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 ODWA6i search utility by providing a value for the following fields - on the several search ODWA6i 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 ODWA6i 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 your cursor to the TARGET workarea where you will execute the merge
4. Highlight subsequently 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 section Request Check-list for a checked-in status of a checked-out element to enforce a check-in 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  manual interfere whenever the wizard cannot make a specific choice for a each difference.
7. Save the merge operation - the  merge itself does not automatically creates 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 in differences of folder memberships (see step 6 of the section Merge guidelines for structured elements and files).