3 Setting Up and Using the Multiuser Development Environment

Multiuser development (MUD) provides a mechanism for concurrent development on overlapping code bases. Oracle Business Intelligence provides a MUD environment that manages subsets of metadata, in addition to multiple users, by providing a built-in versioning system for repository development. This chapter explains how to set up and use the multiuser development environment in Oracle Business Intelligence, including defining projects, setting up the multiuser development directory, checking out and checking in projects, and merging metadata.

See also "Managing the Repository Lifecycle in a Multiuser Development Environment" for additional information about working in a multiuser development environment.

This chapter contains the following topics:

About the Multiuser Development Environment

In Oracle Business Intelligence, multiuser development facilitates the development of application metadata in enterprise-scale deployments. Application metadata is stored in a centralized metadata repository (RPD) file. The Administration Tool is used to work with these repositories.

The following are examples of how you might use a multiuser development environment:

  • Several developers work concurrently on subsets of the metadata and then merge these subsets back into a master repository without their work conflicting with other developers. For example, after completing an implementation of data warehousing at a company, an administrator might want to deploy Oracle Business Intelligence to other functional areas.

    Note:

    In this chapter, "master repository" refers to the copy of a repository in the multiuser development directory
  • A single developer manages all development. For simplicity and performance, this developer might want to use the multiuser development environment to maintain metadata code in smaller chunks instead of in a large repository.

In both examples, an administrator creates projects in the repository file in the Administration Tool, then copies this repository file to a shared network directory (called the multiuser development directory). Developers are able to check out projects, make changes and then merge the changes into the master repository. When developers check out projects using the Administration Tool, files are automatically copied and overwritten in the background. Therefore, it is important for the administrator to perform setup tasks and for the developers to perform check-out and check-in procedures carefully, paying close attention to the Administration Tool messages that appear.

When developers check out projects, repository files are not automatically copied or overwritten. Instead, the Administration Tool creates two new files when projects are checked out: one to hold the original project data, and one to hold the project changes.

For example, when a repository developer checks out project A from master.rpd in the C:\multiuser development directory, the Administration Tool extracts all metadata related to project A and prompts the developer for a new file name to save the data. When the developer chooses a new file name, for example Mychanges.rpd, the Administration Tool creates two new files:

  • A file called MyChanges.rpd that will contain the changes made by the developer

  • A file called originalMyChanges.rpd that contains the original project data

The originalMyChanges.rpd file helps determine what changes have been made by the developer in Mychanges.rpd. This information is needed during the multiuser development merge process.

Note:

To reduce storage needs, repositories in Oracle Business Intelligence Enterprise Edition 11g Release 1 (11.1.1) are stored in a compressed format. Because of this, you may notice that the size of an RPD file opened and saved in this release is significantly smaller than the size of RPD files from previous releases.

About the Multiuser Development Process

Multiuser development presupposes a clear understanding of customer technical and business objectives. It also requires that you follow clearly defined development processes and adhere rigorously to those processes, including consistent merging and reconciliation practices.

The following procedure shows the general steps to follow when deploying a multiuser development environment. The first three steps are usually performed by an administrator, and the remaining steps are usually performed by one or more developers.

To deploy a multiuser development environment:

  1. Define projects to organize voluminous metadata into manageable components. See "Creating Projects" for more information. Consider these tips:

    • Use smaller RPDs to shorten and simplify development effort and unit testing.

    • Organize development resources by projects to spread workload and reduce inconsistencies and overwrites.

  2. Set up a shared network directory to use as the multiuser development directory.

  3. Copy the master repository to the multiuser development directory.

  4. Extract one or more projects for local development.

  5. Merge repository objects and resolve conflicts.

    • Because metadata objects are often highly interrelated, several developers could be working on the same objects.

    • When configuration conflicts occur during check in, developers are prompted for the correct process.

    • The master repository is locked for check-ins when you merge your local changes. However, other developers can still perform check-outs.

  6. Publish changes to the network.

    • Many developers can simultaneously work on the same objects, but only one can publish at a time. During the publish, no check-outs are allowed.

  7. Use Logging and Backup features to identify points of erroneous or incorrect configuration.

    • The log file tracks multi-development activity, along with comments.

    • The master repository and developer repositories are automatically backed up for future reference and for use in manual rollback.

Setting Up Projects

Projects are the central enabler of metadata management. A project consists of a discretely-defined subset of the repository metadata, in the form of groups of logical stars with associated metadata. A project has the following characteristics:

  • Is largely defined by logical fact tables in the applicable business model

  • Automatically adds related logical dimension tables and other metadata during extract

  • Can have one to many logical fact tables

For projects that are just beginning, the best practice is to begin with a repository containing all the necessary physical table and join definitions. In this repository, you create a logical fact table as a placeholder in the Business Model and Mapping layer and a subject area as a placeholder in the Presentation layer. As you add business model and subject area metadata, new projects based on individual subject areas and logical facts can be created.

Note:

Only one person at a time can create projects in a master repository.

This section contains the following topics:

About Projects

Projects can consist of Presentation layer subject areas and their associated business model logical facts, dimensions, groups, users, variables, and initialization blocks. Administrators can create projects so that developers and groups of developers can work on projects in their area of responsibility.

The primary reason to create projects is to support multiuser development. During the development process, you can split up the work (metadata) between different teams within your company by extracting the metadata into projects so that each project group can access a different part of the metadata.

In addition to multiuser development, you may want to create projects for licensing reasons. Before releasing a new software version, you may want to ensure that only the metadata that is relevant to the licensed application is in a project and that everything is consistent and complete. You can accomplish this by adding only the fact tables that are relevant to the application.

Project extractions are fact table centric. This ensures that project extracts are consistent and makes licensing much easier to manage.

About the Project Dialog

In the Project dialog, the left pane contains objects that you can use to create a project. The objects in the right pane are all the objects you chose (directly or indirectly) that reflect the complete set of data that makes each addition consistent. For example, if you select a subject area from the top node of the left-hand tree to add to your project, underlying fact tables of other subject areas are automatically added if needed to make the extract consistent.

The following describes the left pane of the Project dialog:

  • You can choose to group fact tables by Business Model or Subject Area, to help select the fact tables you want. Typically, grouping fact tables according to which ones are used by a particular subject area is a more convenient way to choose fact tables for your project. Note that a fact table can be associated with multiple subject areas, but belongs to one and only one business model.

    Although it appears that you can add a subject area from the top node when you group facts by subject area, you are actually adding only the underlying fact tables. The subject areas only appear as choices to help you to add the elements you want in your project. Additionally, it adds any other objects that are necessary to make the extract consistent. To add an actual subject area, use the Presentation node at the bottom of the tree.

  • When grouped by business model, the left pane displays only facts that belong to the business model.

  • The Presentation node contains presentation layer objects. You must explicitly include these objects in your project if you want to work with them; they are not added automatically.

    If you add presentation objects that are not related to any fact tables in the project, a warning appears when you click OK. The consistency checker also notes this discrepancy.

The right pane of the Project dialog shows the objects you select to be extracted, such as fact tables (under the Business Models folder), Presentation layer objects (under the Presentation folder), users, application roles, variables, and initialization blocks. These objects are extracted when you click OK.

Figure 3-1 shows the Project dialog.

Figure 3-1 Project Dialog with Fact Tables Grouped by Business Model

Description of Figure 3-1 follows
Description of "Figure 3-1 Project Dialog with Fact Tables Grouped by Business Model"

Creating Projects

When creating a project, you typically select a subject area or a subset of logical fact tables related to the selected subject area, and the Administration Tool automatically adds any business model and Physical layer objects that are related. An object can be part of multiple projects. Alternatively, if you choose to group facts by business model, you can select a particular business model or a set of logical fact tables that are part of a business model. You also need to explicitly add any Presentation layer objects if you want them to be part of your project.

Note that although the project definition itself does not include Physical layer objects, these objects are extracted and determined through the project definition.

After you create projects, they become part of the metadata and are available to multiple developers who need to perform development tasks on the same master repository. When defined this way, projects typically become a consistent repository after a developer checks out the projects and saves them as a new repository file.

To create a project for a multiuser development environment:

  1. In the Administration Tool, choose File > Open > Offline.

  2. In the Open dialog, select the repository that you want to make available for multiuser development, then click OK. Provide the repository password, then click OK again.

  3. Select Manage, then select Projects.

  4. In the Project Manager dialog, in the right pane, right-click and then select New Project.

    The left pane contains the objects that are available to be placed in a project. The right pane contains the objects that you select to be part of the project.

  5. In the Project dialog, type a name for the project.

  6. Choose whether to group facts by business model, or subject area. It is typically more convenient to group facts by subject area.

  7. Perform one or more of the following steps to add fact tables to your project:

    • In the left pane, select a subject area or business model and then click Add. The Administration Tool automatically adds all the associated logical fact tables.

    • In the left pane, expand the subject areas or business models and select one or more logical fact tables that are related to the subject area or that are within the business model, then click Add.

      The project is defined as explicitly containing the selected logical fact tables and implicitly containing all logical dimension tables that are joined to the selected logical fact tables (even though they do not appear in the right pane).

    See "About the Project Dialog" for more information about the objects that appear in the left and right panes.

  8. To remove fact tables from the project, in the right pane, select a fact table and click Remove. You can also remove all fact tables associated with a subject area or business model by selecting a subject area or business model and clicking Remove.

  9. Optionally, add any application roles, users, variables, or initialization blocks needed for the project. Although objects like variables and initialization blocks that are directly referenced by other extracted objects are included automatically, you might want to include objects in your project that are not referenced. For example:

    • If you are using initialization blocks for authentication, include any necessary initialization blocks.

    • Include repository variables or other objects that are not yet referenced by other objects, but that you might want to use in future repository development.

    • Include users and application roles that are currently being used, or will be used in the future, as part of your data access security settings.

    Tip: You may want to add the top node for each object type (for example, Variables), then selectively remove individual objects from the right pane.

  10. Select the Presentation layer objects that you want to include in your project from the left pane and click Add. You must add these objects to see them in the project; they are not added automatically.

    You can also remove particular presentation tables or columns from the project definition by double-clicking the object in the right pane, or selecting the object and clicking Remove.

    Note:

    If you do not see the set of subject areas you expect after the project is created, edit the project to explicitly add the subject areas you need.
  11. Click OK.

About Converting Older Projects During Repository Upgrade

When you upgrade a repository from Oracle Business Intelligence versions before 10.1.3.2, the project definition is upgraded. During the upgrade, the project definition, subject areas, target levels, list catalogs, and existing fact tables are automatically converted into simple fact tables in the following way:

  • Get presentation columns related to the target levels through the qualifying keys.

  • Get presentation columns related to the list catalogs through the qualifying keys.

  • Get presentation columns related to the subject areas.

  • Get all the logical columns from all the presentation columns.

  • Get all the logical columns from the fact tables in the project.

  • Get the fact tables from all the logical columns.

After the upgrade, projects contain only simple fact tables. All the security objects remain unchanged.

In addition, projects in repositories from any version before 11g Release 1 (11.1.1) are upgraded so that they explicitly contain Presentation layer objects. In previous releases, Presentation layer objects were implicitly included based on the permissions of the users included in the project.

Setting Up the Multiuser Development Directory

To prepare for multiuser development, an administrator performs the following tasks:

  • Identify or create a shared network directory that will be dedicated to multiuser development.

  • After creating all projects, copy the repository file in which you created the projects to the multiuser development directory where it will be used as your master repository for multiuser development.

After the administrator has identified the multiuser development directory and copied the repository file, developers must set up to the Administration Tool to point to the multiuser development directory before they can check out projects.

This section contains the following topics:

Identifying the Multiuser Development Directory

After defining all projects, the administrator must identify or create a shared network directory (called the multiuser development directory) that all developers can access, and then upload the new master repository to that location. This shared network directory should be used only for multiuser development. This directory typically contains copies of repositories that need to be maintained by multiple developers. The multiuser development directory must be on a Windows system.

Developers create a pointer to the multiuser development directory when they set up the Administration Tool on their computers.

Caution:

The administrator must set up a separate, shared network directory that is dedicated to multiuser development. If not set up and used as specified, critical repository files can be unintentionally overwritten and repository data can be lost.

Copying the Master Repository to the Multiuser Development Directory

After the multiuser development directory is identified, the administrator must copy the master repository file to the multiuser development directory. Projects from this master repository will be extracted and downloaded by the developers who will make changes and then merge these changes back into the master repository.

After you copy the repository to the multiuser development network directory, notify developers that the multiuser development environment is ready.

Setting Up a Pointer to the Multiuser Development Directory

Before checking out projects, each developer must set up their Administration Tool to point to the multiuser development directory on the network. The Administration Tool stores this path in a hidden Windows registry setting on the workstation of the developer and uses it when the developer checks out and checks in objects in the multiuser development directory.

Note:

Until the pointer is set up, the multiuser options are not available in the Administration Tool.

Initially, the network directory contains the master repositories. The repositories in this location are shared with other developers. Later, the network directory contains additional multiuser development history files, including historical subsets and repository versions. Do not manually delete any files in the multiuser development directory; these files are important and are used by the system.

When setting up the pointer, the developer can also complete the Full Name field. Although the field is optional, it is recommended that the developer complete this field to allow other developers to know who has locked the repository. The Full Name value is stored in HKEY_CURRENT_USER in the registry, and is unique for each login.

To set up a pointer to the multiuser development directory:

  1. From the Administration Tool menu, choose Tools > Options.

  2. In the Options dialog, click the Multiuser tab.

  3. In the Multiuser tab, for Multiuser development directory, enter the full path to the network directory.

    Alternatively, click Browse, select the multiuser development directory, and then click OK.

  4. In the Full Name field, type your complete name, then click OK.

Making Changes in a Multiuser Development Environment

During check-out and check-in, a copy of the master repository is temporarily copied to the developer's local repository directory (typically, ORACLE_INSTANCE\bifoundation\OracleBIServerComponent\coreapplication_obisn\repository by default). After checking out projects and making changes in a local repository file, each developer can check in (merge) changes into the master repository or discard the changes.

To make changes in a multiuser development environment, perform the tasks described in the following sections:

Checking Out Repository Projects

After setting up a pointer to the multiuser development default directory, a developer can check out projects, change metadata, and test the metadata. In the File > Multiuser submenu, the Checkout option is only available when there is a multiuser development directory defined in the Multiuser tab of the Options dialog.

If a developer checks out a local repository and attempts to exit the application before publishing it to the network or discarding local changes, a message appears to allow the developer to select an action. See "About Closing a Repository Before Publishing It to the Network" for more information.

This section contains the following topics:

About Repository Project Checkout

During checkout, the Administration Tool performs the following tasks:

  • In the developer's local repository directory, the Administration Tool makes a temporary copy of the master repository.

    Note:

    If a repository with that name exists in this location, the developer is asked to confirm overwriting the existing repository. If the developer clicks Yes, the existing local repository is immediately overwritten in the background and after the new repository is saved, the temporary master repository file is automatically deleted.
  • In the developer's local repository directory, the Administration Tool saves a local copy of the selected projects in a new repository, such as Metadata1.rpd. The developer provides a name for the local copy. The developer makes metadata changes in this file. The number is incremented for each checkout for that session.

  • In the developer's local repository directory, the Administration Tool saves a second local copy of the new repository, adding 'original' as the prefix (for example, originalMetadata1.rpd).

  • After the developer saves the new repository file, check out is complete. In the developer's local repository directory, the temporary copy of the master repository is automatically deleted.

    Caution:

    When the developer selects and saves the projects to a local repository file, the Administration Tool does not place a lock on the projects in the master repository on the shared network drive. Therefore, nothing physically prevents others from working on the same project. To determine if a project has been checked out, you need to look in the log file in the multiuser development directory on the shared network drive.

Checking Out Projects

This section explains how to check out projects using the Administration Tool.

To check out projects:

  1. From the Administration Tool menu, choose File > Multiuser > Checkout.

  2. If there is more than one repository in the multiuser development directory, the Multiuser Development Checkout dialog appears. Select the appropriate repository, and then click OK.

    This dialog does not appear if there is only one repository in the multiuser development directory.

  3. In the Extract from dialog, type the repository password, and then click OK.

    If no projects exist in the repository, a message appears and the repository does not open.

  4. If there is more than one project in the master repository, the Browse dialog appears. Select the projects that you want to be part of your project extract, and then click OK.

    Figure 3-2 shows the Browse dialog for selecting projects.

    Figure 3-2 Browse Dialog for Selecting Projects

    Description of Figure 3-2 follows
    Description of "Figure 3-2 Browse Dialog for Selecting Projects"

    If only one project exists in the master repository, it is selected automatically and the Browse dialog does not appear.

  5. In the Create new subset repository dialog, type a name for the new repository (for example, Metadata1.rpd) and then click Save.

    A working project extract repository is saved on your local computer. The name is exactly as you specified and is opened in offline mode. A log file is also created.

    Caution:

    A second copy of the project extract repository is saved in the same location. The name of this version contains the word "original" added to the beginning of the name that you assigned to the repository extract. Do not change the original project extract repository. It is used during the multiuser development merge process, and when you want to compare your changes to the original projects.

Using the extractprojects Utility to Extract Projects

You can use the Oracle BI Server utility extractprojects to extract projects from a given repository without the overhead of the MUD environment. You can run this utility on any platform supported by the Oracle BI Server.

The extractprojects utility generates an RPD file that includes the set of projects you specify. The utility does not perform other tasks that are performed when you check out projects using the Administration Tool, like saving an original repository file or tracking the extract as a check-out in the MUD directory.

Before running extractprojects, you must first run bi-init.cmd (or bi-init.sh on UNIX systems) to launch a command prompt that is initialized to your Oracle instance. You can find this utility in:

ORACLE_INSTANCE/bifoundation/OracleBIApplication/coreapplication/setup

Then, run extractprojects from the resulting command prompt with the desired options. You can run the utility from this directory with no arguments or parameters to see usage information.

The utility takes the following parameters:

extractprojects -B base_repository_name -O output_repository_name {-I input_project_name} [-P repository_password] [-L]

Where:

base_repository_name is the name and path of the repository from which you want to extract projects.

output_repository_name is the name and path of the repository generated by the utility.

input_project_name is the name of a project you want to extract. You can enter multiple projects. Be sure to precede each project entry with -I (for example, -I project1 -I project2). If the project name contains spaces, enclose it in double quotes (for example, "project 1").

repository_password is the password for the repository from which you want to extract projects.

Note that the repository_password argument is optional. If you do not provide the password argument, you are prompted to enter the password when you run the command. To minimize the risk of security breaches, Oracle recommends that you do not provide password arguments either on the command line or in scripts. Note that the password argument is supported for backward compatibility only, and will be removed in a future release.

- L enables logging. When logging is enabled, a log file in the format ProjExtr.YYYYMMDD.HHMMSS.xml is created in the Oracle BI Server logging directory. For example:

ORACLE_INSTANCE/diagnostics/logs/OracleBIServerComponent/coreapplication_obisn/ProjExtr.20100616.082904.xml

Example 

The following example extracts project1 and project2 from my_repos.rpd and creates a new repository called extract_repos.rpd:

extractprojects -B my_repos.rpd -O extract_repos.rpd -I project1 -I project2
Give password: my_rpd_password

Note:

Be sure to provide the full pathnames to your repository files, both the input file and the output file, if they are located in a different directory.

About Changing and Testing Metadata

Most types of changes that can be made to standard repository files are also supported for local repository files. Developers can add new logical columns, logical tables, change table definitions, logical table sources, and so on. Developers may also work simultaneously on the same project locally. It is important to note, however, that Oracle Business Intelligence assumes the individual developer understands the implications these changes might have on the master repository. For example, if a developer deletes an object in a local repository, this change is propagated to the master repository when local changes are merged without a warning prompt.

To ensure metadata integrity, you should not remove a physical column unless there are no logical table source mappings to that physical column. Because of this, if you are using a multiuser development environment, you cannot delete a logical column and its associated physical column at the same time. Instead, you must first delete the logical column and perform a merge. Then, you can delete the physical column and perform another merge to safely remove the object.

You should not modify physical connection settings in a local repository. These are intentionally not propagated, and developers should not test the master connection pool settings in local environments. Instead, developers should apply settings for their local test data sources to perform unit testing of their model changes.

Physical connection settings, security settings, and database feature table changes are not retained in a multiuser development merge to prevent developers from overwriting passwords and other important objects in the master repository.

After making changes to a local repository, the developer can edit the local NQSConfig.INI file, enter the name of the repository as the default repository, and test the edited metadata.

Note:

DSNs specified in the metadata must exist on the developer's workstation.

About Multiuser Development Menu Options

After the local developer makes changes, tests the changes, and saves the repository locally, the local developer can perform the following tasks from the File > Multiuser submenu:

  • Compare with Original. Compares the working extracted local repository to the original extracted repository. When this option is selected, the Compare repositories dialog opens and lists all the changes made to the working extracted repository since you checked out the projects.

  • Merge Local Changes. Locks the master repository on the network multiuser directory to allow you to check in your changes. See "Checking In Multiuser Development Repository Projects" for more information.

  • Publish to Network. After you successfully merge your changes, the master repository opens locally and the Publish to Network submenu item is available. When you select this option, the lock is removed, the repository is published, and the repository closes. See "Checking In Multiuser Development Repository Projects" for more information.

  • Undo Merge Local Changes. Rolls back any previously merged local changes, and leaves the repository checked out so that you can make additional changes and then merge your local changes again. This option is only available after you have already merged local changes.

  • Discard Local Changes. Any time after check out and before check in, you can discard your changes. When you select this option, the working repository closes without giving you an opportunity to save your work.

    Caution:

    If you select this option, there is no opportunity to change your mind. For example, no confirmation dialog appears.

About Closing a Repository Before Publishing It to the Network

If you attempt to close an unpublished, locked repository without selecting an option in the File > Multiuser submenu, the Closing MUD repository dialog opens with the following options:

  • Publish repository. Publishes the merged repository to the network share as the new master, releases the lock on the master, and the event is logged. This option is available after a Merge Local Changes event occurs. This option is also available on the File > Multiuser submenu.

  • Discard local changes. Releases the lock on the master repository and records the event in the log. This option is available after a Checkout or Merge Local Changes is performed and can be found on the File > Multiuser submenu.

  • Close repository and keep lock. This closes the repository, leaving the master repository locked.

  • Undo merge local changes. Rolls back your previously merged local changes, and leaves the repository checked out so that you can make additional changes and then merge your local changes again.

Checking In Multiuser Development Repository Projects

After changing and testing the metadata on a local computer, the developer must check the projects into the master repository in the multiuser development directory. Only one developer at a time can merge metadata from a local repository into the master repository. Therefore, the master repository is locked at the beginning of the merge process.

The Oracle BI repository development process uses a three-way merge to manage concurrent development. Metadata merges are done first on local environments and then merged with the master repository. A three-way merge identifies local changes based on the following repository characteristics:

  • The Master RPD

  • The Baseline RPD or Master RPD snapshot at time of project extraction

  • The current locally developed and changed RPD

Changes are managed by merge and reconciliation. Most of the merging process is automatic, and changes do not conflict. In case of any conflicting metadata sources, developers can locate and resolve them.

An administrator can also merge the changes from multiple repositories manually, or import objects from different repositories outside of a particular MUD environment.

Make sure to merge your changes frequently. The merge process is very complex and can become difficult if there are too many changes. See Appendix D, "Merge Rules" for more information about how objects are merged during the merge process.

This section contains the following topics:

About the Multiuser Development Merge Process

The merge process involves the following files:

  • Original of the local (subset) repository. Contains the state of the projects as originally extracted. This repository name begins with "original." An example of the file name for this copy might be originalDevelopment2.rpd. This version is stored in the same location as the modified (or working) version of the local repository.

  • Modified local (subset) repository. Contains the extracted projects after being modified by the developer. This version is stored in the same location as the original version of the local repository.

  • Latest master repository in the multiuser development directory. Note that this file may have been modified by other developers before this merge.

During the merge, the Administration Tool checks for added objects and if found, a warning message appears. The following list describes what happens during this step:

  • Warning about added objects. When a person checks out a project, they have the ability to modify that project in any way and check it back in. Deletions and modifications are ways in which the integrity of the project is maintained. However, adding objects might introduce objects into the repository that do not belong to any project. Therefore, all project related objects are checked and if a new object is found, a warning message appears.

    Caution:

    You must add newly created metadata to the project definition in the master repository for it to be visible in future extracted versions of the project. For example, if a developer checks out a project, adds a new object, and then checks it in, the new object is not visible in extracted versions of the project until it is explicitly added to the project definition. See "Creating Projects" for instructions.
  • Aggregation of related objects. In the warning message, only the parent object is reported. The Administration Tool aggregates all the objects to make the message more usable. For example, if a developer added a new business model, only the business model appears in the warning message to the user, not the tables, columns, dimensions, and so on.

When a developer publishes changes to the network, the following actions occur:

  • The master repository in the multiuser development directory is overwritten with the repository containing the developer's changes.

  • The master_repository.lck file is deleted. If another developer checks out the changed project from the master repository, the changes made by the first developer are exposed to the other developer.

How are Multiuser Merges Different from Standard Repository Merges?

The multiuser development check-in process uses the same technology as the standard repository merge process with a few important differences. See "Performing Full Repository Merges" for more information about the standard repository merge.

The following list describes the differences that occur during a multiuser development merge:

  • Inserts (created objects) are applied automatically. Because a subset of the master repository is being used as the original repository, most objects in the master repository appear to be new. This would result in many unnecessary prompts that the developer would have to manually approve. Therefore, new objects are created without a prompt during a multiuser development merge.

  • Conflicts that are not inserts but are resolved because of the automatic inserts are applied without a prompt during a multiuser development merge.

  • The database and connection pool properties in the master repository take precedence over the same properties on the developer's computer. This precedence are applied without a prompt during a multiuser development merge.

  • Changes to security settings are not retained when you perform a MUD merge to prevent developers from overwriting passwords and other important objects in the master repository.

To change security settings or database features in a multiuser development environment, you must edit the master repository directly. To do this, remove the master repository from the multiuser development directory, edit it in offline mode, then move it back.

Checking In Projects

When the check-in process begins, the following actions occur:

  • The Administration Tool determines if the master repository is currently locked. If not, it locks the master repository, preventing other developers from performing a merge until the current merge is complete, and records the lock in the log file.

  • For other developers, the Merge Local Changes option on the File > Multiuser menu is unavailable until the current check-in process has been successfully completed.

  • The Administration Tool automatically copies the current version of the master repository from the multiuser development directory to the local repository directory on the developer's computer (typically ORACLE_BI_HOME\orainst\bifoundation\OracleBIServerComponent\coreapplication\repository) and updates the log files in the local and multiuser development directories. This is necessary because the master repository in the multiuser development directory might have changed after the developer checked out the projects.

To check in projects to the master repository:

  1. In the Administration Tool, select File > Multiuser > Merge Local Changes, then click Yes if prompted to save changes.

  2. In the Lock Information dialog, in the Comment field, type a description of the changes that you made, then click OK.

    Figure 3-3 shows the Lock Information dialog.

    Figure 3-3 Lock Information Dialog

    Description of Figure 3-3 follows
    Description of "Figure 3-3 Lock Information Dialog"

  3. If there are any conflicts, the Merge Repository Wizard opens and displays the Define Merge Strategy screen. Make merge decisions about whether to include or exclude objects by choosing Current or Modified from the Decision list. When you select an object in the decision table, the read-only text box below the decision table describes what changes were made to that object in the current repository. You can also click View Change Statistics to see a summary of changes. Click Finish when you are finished making merge decisions.

    See "Performing Full Repository Merges" for additional information about the Define Merge Strategy screen.

    A lack of conflicts does not mean that there are no differences between the repositories. Instead, it means that there are no decisions that have to be explicitly made by the developer to check in changes. See "How are Multiuser Merges Different from Standard Repository Merges?" for information about conflicts that are resolved automatically in a MUD merge.

    In both cases, a CSV file is created in the local directory that contains details of the merged changes.

  4. After you confirm all the changes, click Save.

    This saves the merged repository locally, and then uploads this repository to the multiuser development directory with an incremented numeric file extension (for example, Master_Sales.000, Master_Sales.001, and so on).

    At this point, the changes made by the developer are still not saved to the master repository in the multiuser development directory.

  5. To commit these changes to the master repository in the multiuser development directory, select File > Multiuser > Publish to Network, then click OK.

    The master repository in the multiuser development directory is overwritten with the copy of the repository containing the developer's changes.

Tracking Changes to the Master Repository

You can find a summary of the development activities on the master repository in master_repository.log. This log contains a record of the following activities:

  • Projects that have been checked in and checked out and when these actions occurred

  • The Windows login name and computer name initiating the transaction

  • When locks are created and removed

Branching in Multiuser Development

Branching is a further refinement of the merging development process. Branching can provide higher efficiencies over large development teams that have overlapping releases, but it requires significant administrative overhead.

This section contains the following topics:

About Branching

In branching, developers work on private branches to isolate their code from other developers and merge changes back to the main branch. Different strategies can be followed, depending on the size of the development team.

In the Simple Development Model, all development occurs on a single main branch. This strategy has the following characteristics:

  • Only for emergency fixes

  • Checkouts may not be most current code

  • Carries a stability risk for the mainline branch

Figure 3-4 shows the Simple Development Model.

Figure 3-4 Simple Development Model

Description of Figure 3-4 follows
Description of "Figure 3-4 Simple Development Model"

In the Small Team Development Model, development occurs on a single Dev branch, with a separate Main branch strictly for releases. This strategy has the following characteristics:

  • The Mainline is the official release branch

  • Development occurs on a separate branch

  • Stable code is merged back to Main at key milestones

  • Branches are synchronized periodically

Figure 3-5 shows the Small Team Development Model.

Figure 3-5 Small Team Development Model

Description of Figure 3-5 follows
Description of "Figure 3-5 Small Team Development Model"

In the Multi-Team, Multi-Release Model, development occurs on multiple Dev branches, again with a separate Main branch strictly for releases. This strategy has the following characteristics:

  • Supports more efficiency over disparate teams

  • Development occurs on separate branches

  • Stable code is merged back to Main at key milestones

  • Branches are synchronized periodically

Figure 3-6 shows the Multi-Team, Multi-Release Model.

Figure 3-6 Multi-Team, Multi-Release Model

Description of Figure 3-6 follows
Description of "Figure 3-6 Multi-Team, Multi-Release Model"

Using the Multi-Team, Multi-Release Model in Oracle Business Intelligence

Using complex branching strategies in Oracle Business Intelligence requires attentive organization of repository files, as well as altering the Multiuser setting in the Administration Tool. The following procedure provides an overview of the required steps.

To use the multi-team, multi-release model branching strategy:

  1. Create a Main repository (Master Repository) and store it in the Master multiuser development directory.

    • Projects must be explicitly defined.

    • Branch developers should not have access to the Master directory.

  2. Create a subset of branch repositories by extracting from Main and storing them as the Team1 and Team2 multiuser development directories. The Main and Team RPDs must be stored and secured in separate directories on the network.

  3. Developers must check out, develop, merge, and publish from their respective Team RPDs. Developers A1 through A3 and B1 through B3 should manage their metadata work and merge to their Team repository.

    • Teams 1 and 2 must maintain their own repositories and periodically synchronize from Main to Team branches.

    • The Team repositories must be merged back into and published in the Main repository.

  4. One specific group (for example, release management) should manage all project definitions, perform merges, publish, and synchronize the Team RPDs back to Main.

Synchronizing RPD Branches

For large development teams, it is a good practice to perform periodic branch synchronization as Main changes, in order to ease the ultimate Team check-in. Use the Administration Tool to synchronize repositories in a three-way merge.

To synchronize repository branches:

  1. Check in all changes from your Team development branch and open the RPD in the Administration Tool. This the current repository.

  2. Extract a fresh Branch subset from Main. This is the modified repository.

  3. In the Administration Tool, select File, then select Merge and browse to the backup of the previous Branch subset. This is the original repository.

  4. Resolve all issues and perform the merge.

    The RPD named in the Save merged repository as field becomes the new branch development RPD and is called the Original in future synchronizations.

Viewing and Deleting History for Multiuser Development

You can view and delete the development history of a multiuser development repository.

This section contains the following topics:

Viewing Multiuser Development History

You can view the development history of a multiuser development repository. In the Administration Tool, multiuser development history is only available when no repository is open and after the administrator sets up the shared network directory. This prevents the confusion that could occur if a user opened a history log that did not match an open, unrelated repository.

To view multiuser development history:

  1. Open the Administration Tool.

  2. Without opening a repository, select File > Multiuser > History.

  3. In the Multiuser Development History dialog, select a repository.

    A list of all master repositories in the multiuser development directory appears. If directory contains only one master repository, it is selected by default, and no list appears.

  4. In the Open Offline dialog, type the password for the repository. The Multi User History dialog appears.

    Figure 3-7 shows the Multi User History dialog.

    Figure 3-7 Multi User History Dialog

    Description of Figure 3-7 follows
    Description of "Figure 3-7 Multi User History Dialog"

  5. In the Multi User History dialog, right-click a row and select an option. Table 3-1 describes the options in the Multi User History dialog.

    Tip: To see details for all revisions, right-click in the background with no rows selected and select View > Details.

    Table 3-1 Options in the Multi User History Dialog

    Action Description

    View > Repository

    Loads the selected master version of the repository in the Administration Tool in read-only mode.

    View > Prior to Merge > Projects

    Loads the selected version of a modified subset repository in the Administration Tool in read-only mode.

    View > Conflict Resolution

    Loads all necessary repositories of the selected version. Also shows the Merge dialog in read-only mode with all selected decisions as they were during the Merge Local Changes activity at that time. Double-clicking a row for a version with conflict resolutions has the same effect as selecting this menu item.

    Note: This menu item is only enabled for versions that had conflict resolutions.

    View > Details

    Displays a log with details for the selected versions, or displays details for all versions if no specific versions are selected.

    View > Prior to Merge > Changes

    Compares modified subset repository of the selected version with original subset repository and shows all changes made by the user in the selected version.

    Find and Find Again

    Lets you search the list.

    Select All

    Selects all items displayed in the dialog.

    Delete

    Available only to multiuser development administrators.


Deleting Multiuser Development History

Only multiuser development administrators can delete history. Administrators are defined in a special hidden option file in the multiuser development directory. See "Setting Multiuser Development Options" for more information.

An administrator can delete the entire MUD history, or the oldest 1 to n versions. It is not possible to delete versions in the middle of the range. For example, an administrator cannot delete version 3 if there are still versions 1 and 2. If an administrator deletes the entire MUD history, newly assigned version numbers restart at version 1.

Setting Multiuser Development Options

You can create a multiuser development option file to specify options for multiuser development. The option file is a text file, in standard Windows INI format. It has the following properties and characteristics:

  • The option file must be placed in the multiuser development directory. The file has the same name as the corresponding master repository, but with an .opt extension. For example, for \\network\MUD\sales.rpd, create an option file called \\network\MUD\sales.opt.

  • The file should have the Hidden flag turned on.

  • In general, the option file should be managed only by multiuser development administrators. To ensure this, you may want to change the sharing permissions for the file.

The following example shows a multiuser development option file:

[Options]
BuildNumber = Yes
Admin = admin1;admin2
Mandatory Consistency Check = Yes
Equalize During Merge = Yes

Options that are not explicitly set are turned off by default. To turn an option on, set its value to Yes. To turn an option off, either remove it from the option file, or set its value to No.

Table 3-2 explains the options in the multiuser development option file.

Table 3-2 Options in the Multiuser Development Option File

Option Description

BuildNumber

When set to Yes, the build version of the Administration Tool is displayed in the MUD history.

Admin

Lists multiuser development administrators. Administrators must be defined in the option file before they can delete MUD history.

Administrators are defined by their computer/network login names. When multiple administrators exist, administrator names are separated by semicolons. For example:

Admin=jsmith;mramirez;plafleur

Mandatory Consistency Check

When set to Yes, the publish step performs a consistency check. Publishing cannot proceed unless there are no errors in the given repository.

Equalize During Merge

When set to Yes, the multiuser development merge process performs mandatory equalization during MUD merges. Note that setting this option to Yes affects the performance of the merge process.