Skip Headers
Oracle® Fusion Middleware Metadata Repository Builder's Guide for Oracle Business Intelligence Enterprise Edition (Oracle Fusion Applications Edition)
11g Release 1 (11.1.1)

Part Number E20836-05
Go to Documentation Home
Go to Book List
Book List
Go to Table of Contents
Go to Index
Go to Feedback page
Contact Us

Go to previous page
Go to next page
PDF · Mobi · ePub

A Managing the Repository Lifecycle in a Multiuser Development Environment

This appendix provides best practice information for managing the lifecycle of the Oracle BI repository when you are using a multiuser development environment.

Building your Oracle BI repository using the multiuser development environment enables you to do the following:

This appendix covers the development lifecycle of the Oracle BI repository. It does not cover the development lifecycle of the Oracle BI Presentation Catalog used by Presentation Services. This appendix also does not cover how to use the multiuser development environment for Independent Software Vendor (ISV) organizations building portable BI applications for sale as products.

See also Appendix B, "MUD Case Study: Eden Corporation" for detailed examples of how the multiuser development environment is used in a typical business scenario.

This appendix contains the following topics:

Planning Your Multiuser Development Deployment

This section describes tasks you need to perform as part of the planning phase before beginning multiuser development.

This section contains the following topics:

About Business Organization and Governance Process Best Practices

You need to provide a strong, effective governance process to make decisions about shared resources and to resolve conflicts among the many stake-holders. As in any business process, you must have a strong business sponsor, and the steering committee must be staffed with strong business people who can negotiate effectively and make good decisions that will not change over time. Having an effective governance process has proven to be the single most important factor in achieving successful multiuser development with Oracle Business Intelligence.

Before you begin your multiuser development project, you must first lay out the business value, priorities, roadmap, and requirements, as well as lower level details of the design, as described in Table A-1.

Table A-1 Tasks to Accomplish During the Planning Phase

For... You must...

Strategic requirements

  • Determine which business processes to measure

  • Determine which data sources and subject areas to access

Business requirements for repository objects

  • Select and define metrics, dimensions, and hierarchies

  • Identify objects that will be shared between development teams

  • Resolve conflicts between teams

  • Define Presentation layer subject areas

Security requirements

  • Define Application Roles and corresponding privileges for your user base

  • Define which repository developers can access which metadata and data


  • Determine the styles of multiuser development to use

  • Define areas to break down into MUD projects

  • Determine the owners for metadata objects

Project management

  • Set initiatives - purpose, goals, requirements, scope, schedule, budget

  • Define phases - scope, schedule

  • Allocate resources - hardware, software, databases, developers

  • Decide on a strategy for development branching

  • Prioritize and schedule production updates from different development teams


  • Negotiate service level agreements

  • Coordinate schedules for updates and downtime

About Technical Team Roles and Responsibilities

This section describes the hands-on roles involved in repository development and its lifecycle. Depending on the size of your company and team, some of these roles might be served by one person.

Repository development roles include:

  • MUD administrator (one for each development team, plus backup)

    • Assigns repository password

    • Sets up and maintains MUD projects

    • Manages the master repository shared directories

    • Manages branches and branch merges

    • Manages repository migrations

    • Manages test and production connection pools

    • Manages independent semantic models (has metadata read/write privileges for all models)

  • Repository developer (many per development team)

    • Knows the repository password

    • Owns, operates, and maintains a personal development sandbox that includes all necessary Oracle Business Intelligence components

    • Manages user and application role provisioning on their sandbox stack

    • Creates functional and data authorization content in the repository

    • Performs unit testing

    • Performs check-outs, merges, and publishing, as required

  • Production Operations staff

    • Knows the repository password (for managing connection pools and applying patches)

    • Applies updated repositories, and applies XML patch updates to the running BI Server's repository

    • Can log in to production computers and read/write the Oracle Business Intelligence directories or run programs

    • Manages the production file system, including the repository directory, logs, and configuration files

    • Manages the production servers (Administration Server, Managed Servers with Java components, and Oracle Business Intelligence system components like Oracle BI Server and Presentation Services)

    • Manages production security, including provisioning users, groups, and application roles

    • Manages and migrates application roles in production

    • Manages production connection pools (in the case where the MUD administrator does not have security privileges for production connection information)

People in other roles outside the repository development team are also involved. These include people administering the test environment and running the tests, and also the Oracle BI Presentation Catalog developers.

Multiuser Development Architecture

Before you can understand best practices for MUD and repository lifecycle management, you need to understand the architecture of the development environment.

This section contains the following topics:

About Multiuser Development Concepts

This section explains fundamental concepts related to developing and deploying systems for multiuser development.

Oracle BI Repository

The Oracle BI repository is the fundamental artifact under development. It defines all the metadata used by the Oracle BI Server for interpreting user requests, applying role-based security, generating queries to data sources, and post-processing the results. Repositories used in multiuser development environments must be in binary (RPD) format, not MDS XML format.

Application Roles and the Policy Store

A secondary artifact under development is the set of application roles. User object permissions, data access filters, and query limits (governors) are defined against these application roles in the repository logic. Presentation Services also uses application roles for assigning its privileges and permissions.

You can use the default policy store embedded in Oracle WebLogic Server, or you can use a separate external policy store. If you are using the embedded policy store, you define application roles in Fusion Middleware Control, which persists them in the Policy Store in Oracle WebLogic Server. You can then use the Administration Tool in online mode to add application roles from your policy store to your repository at design time. At run time, the Oracle BI Server uses the application roles provisioned to each user to apply the correct security privileges to user requests.

Sandboxes, Projects, and Branches

An instance of the repository is usually edited by only one repository developer at a time. Multiple developers work in parallel on subset instances of the repository, called "projects." They work in separate sandbox environments, and merge their changes into a master repository instance frequently to distribute changes and pick up changes made by others in the team. This approach enables the creation of very large enterprise applications. It also enables independent semantic models to be developed by separate teams and merged into the master repository for production hosting in a single Oracle BI Server cluster. Finally, it enables branching and merging so that teams can work on major projects in parallel, and can even make emergency fixes to the main code line in production without disrupting ongoing development projects.

You typically use the Simple install type when installing a development sandbox.

Single, Shared Repository

Presentation Services connects to just one repository that has been uploaded to the Oracle BI Server. The metadata for all semantic models must reside in this single repository, even if the semantic models share no objects. See "About Multiuser Development Styles" for more information about semantic models in a repository.

Repository Password

The repository file is protected by the repository password. The Oracle BI Server needs this password to open and load the repository at startup. It stores the repository password in the secure Credential Store. You must also enter this password when you open the repository in the Administration Tool or other utilities and line commands. Note that user logon credentials are stored in the identity store, not the credential store.

Oracle BI Presentation Catalog

The Oracle BI Presentation Catalog is an important BI application artifact that contains the metadata that defines reports, dashboards, KPIs, scorecards, and other reporting layer objects. The Oracle BI Presentation Catalog is outside the scope of this document. See "Managing Objects in the Oracle BI Presentation Catalog" in Oracle Fusion Middleware User's Guide for Oracle Business Intelligence Enterprise Edition (Oracle Fusion Applications Edition) for more information about Oracle BI Presentation Catalog development.


The completed repository is migrated to test and production systems using Fusion Middleware Control. No downtime is necessary, because you can refresh clustered production Oracle BI Servers with a rolling restart.

Deployment Parameters During Migration

Some repository parameters must change when migrating a repository between development, test, and production systems, such as connection pool settings. These parameters must change because they are based on the deployment, not the application logic. You can automate these updates using the Oracle BI Server XML API (biserverxmlexec.exe -B). During multiuser development, developers merging in content are automatically prevented from overwriting the master repository test connection pool and database parameters with their local unit test parameters.

Application Role (Policy Store) Migration

There are several options for migrating application roles between development, test, and production systems. For simplicity, this document assumes you will re-key a small number of application role names by hand. For full information about migrating application roles, and other migration considerations, see "Moving Oracle Business Intelligence to a Target Environment" in Oracle Fusion Middleware Administrator's Guide.

Users and the Identity Store

As a best practice, users are not represented by metadata objects in the repository at design time. Also, the repository does not manage or store their credentials. Instead, users must always be provisioned to application roles in the run-time environment to receive privileges. Their credentials, as well as their mapping to application roles through groups, are managed in an external Identity Store. See Oracle Fusion Middleware Security Guide for Oracle Business Intelligence Enterprise Edition for more information.

Setting the Environment for the Administration Tool and Utilities

The current directory structure generalizes the location of metadata, data, and configuration files. For this reason, each program or utility you launch requires an initial setup of the configuration for the Oracle instance to which that program belongs. For command-line utilities, you must first launch the bi-init utility to set the parameters, and then launch the utility from a command line inside the bi-init window. Most Oracle BI Server tools, including the Administration Tool, run the bi-init utility transparently. If you run a command without setting the instance environment first, the program will typically fail to find external files.

See "Running bi-init to Launch a Shell Window Initialized to Your Oracle Instance" for more information.

About Multiuser Development Styles

Choose your style of development based on the size of your team, the number of teams and parallel initiatives, and your requirements for security and availability. Table A-2 shows the multiuser development styles.

Table A-2 Styles of Multiuser Development

Style Description

Serial Development (Figure A-1)

You can use this method if you have a small number of developers and low concurrency. Development users share a repository file through e-mail, a shared directory, or on a shared development system, and only one of them makes changes at a time. They must coordinate with each other on the development schedule.

Serial Development with Patch Files (Figure A-1)

As a variation on serial development, you can share a base binary repository, and ship changes only between users using patch files.

Shared Online Development (Figure A-2)

The best practice is for only one developer at a time to develop metadata in online mode against a single Oracle BI Server and its repository. However, multiple online users are an option for development situations where communication among the team members is frequent, a higher risk of conflicts is acceptable, and minimum administrative overhead is a goal.

MUD (Figure A-3)

The Multiuser Development feature enables over one hundred development users to work in parallel on a shared, enterprise repository. Each user can develop and unit test in a separate sandbox environment, using only manageable-sized subsets of the metadata. When a unit of work is complete, they can automatically merge and publish it into the branch, where other users can pick up those changes and integrate them with their own metadata. When a project phase is ready for promotion, the MUD administrator migrates it to the test environment, and eventually, production. The MUD administrator manages branches and sub-branches to enable parallel development of independent initiatives or fixes, and merges them into the main branch to incrementally migrate them to test and production environments. The MUD administrator also manages fine-grained "projects," which are the manageable-sized repository subsets individual developers check out to their local sandbox environments. See "Understanding the Multiuser Development Environment" for additional information.

MUD with Multiple, Independent Semantic Models (Figure A-3 and Figure A-4)

There might be cases where you need two or more independent semantic models, rather than a single, integrated, enterprise-wide model. This is common due to security requirements, or when unrelated divisions of a business share a common Oracle Business Intelligence infrastructure. The MUD administrator creates a branch for each model, which enables parallel development and integrated testing for each team's semantic model. When an independent semantic model's branch is ready for promotion to production, the MUD administrator simply merges the branch into main. The MUD administrator can set security on the branches so that each developer can only see the semantic model to which they are assigned, and so that only the MUD administrator and selected production operations staff can access the integrated main model.

MUD with Delegated Administration (Figure A-3 and Figure A-4)

When the independent semantic models are developed by different organizations on different schedules, a centralized MUD administrator might not provide the desired level of local control. In this case, you can provide a dedicated MUD administrator for each independent semantic model's branch. The branch administrator operates in the same way as an ordinary MUD administrator.

In this scenario, the MUD super-administrator defines a branch for each organization, checks out the subset repository, and provides it to the branch administrator. When the model is ready for promotion to production, the branch administrator passes the repository back to the super-administrator, who merges it into the main branch for promotion, and then migrates the combined repository to production.

Figure A-1 the serial development style of multiuser development.

Figure A-1 Serial Development

Description of Figure A-1 follows
Description of "Figure A-1 Serial Development"

Figure A-2 shows the shared online development style of multiuser development.

Figure A-2 Shared Online Development

Description of Figure A-2 follows
Description of "Figure A-2 Shared Online Development"

Figure A-3 shows true multiuser development with branching.

Figure A-3 Multiuser Development

Description of Figure A-3 follows
Description of "Figure A-3 Multiuser Development"

Figure A-4 shows the architecture for a repository with multiple, independent semantic models.

Figure A-4 Repository with Multiple, Independent Semantic Models

Description of Figure A-4 follows
Description of "Figure A-4 Repository with Multiple, Independent Semantic Models"

Table A-3 shows which multiuser development styles meet various requirements for security and availability.

Table A-3 Requirements Met by Multiuser Development Styles

Requirement Serial Shared Online MUD with Single Semantic Model MUD with Multiple Semantic Models MUD with Delegated Administration

No administrator






Up to five concurrent developers






More than five concurrent developers






Work on manageable subsets of a large repository, such as Oracle BI Applications






Built-in checkout, merge, and rollback






Host independent semantic models in single repository






Incremental migration of units of work to production






Developers of independent semantic models cannot see each others' metadata




YesFoot 1 

YesFootref 1

Each independent semantic model has its own MUD administrator






Footnote 1 Requires secure MUD Directory. An overall MUD administrator must still have access to all metadata from all teams.

Multiuser Development Sandbox Architecture

When using MUD, each developer works on their own, fully dedicated sandbox Oracle Business Intelligence system. You should set up your sandbox to contain all the components you need for development and unit testing.

First, you need to decide whether to use a UNIX or Windows server for your Oracle Business Intelligence stack. Follow these guidelines:

  • If you choose the Windows-only option, make sure your system has enough memory. Note that you will need additional resources if you choose to host your database on the same hardware. See "System Requirements and Certification" for information about minimum hardware requirements.

  • If you choose the UNIX option, you still need a Windows system to run the Administration Tool. Use the Oracle Business Intelligence Simple install type on the UNIX system, and use the Client install type on the Windows system to install the Administration Tool.

    In online mode, the Oracle BI Server loads the repository from its local repository directory on the UNIX system in:


    Note that the Administration Tool on Windows also points to a local /repository directory by default, but you can use any directory for offline development.

You also need to install a development database. This database can be a dedicated, personal database, or it can be shared among multiple repository developers. Note the following considerations about the development database

  • Platform: You can choose to host your development database on your sandbox computer if you provide enough memory, or you can host it on a centralized, shared server. Both scenarios are shown in Figure A-5.

  • RCU: The database must contain the schemas required by Oracle Business Intelligence. You load these schemas using the Repository Creation Utility (RCU). These schemas enable support for Oracle BI Scheduler and annotations for Oracle Scorecard and Strategy Management, provide sample tables for Usage Tracking, and enable many other features. The Oracle WebLogic Server Managed Servers for Oracle Business Intelligence, and all the services that depend on it, require access to a running database with the required RCU schemas in order to operate.

  • Data Source Schemas: You also need data source schemas for the metadata under development. You can optionally include some data source schemas in your RCU database, or they can be in other databases. Note the following additional information about data source schemas:

    • Test Data: The data source schemas should be loaded with test data. If users are testing read-only metadata, the schemas can be shared among multiple development sandboxes. They can be located on the development sandbox computer if enough memory is available.

    • Multiple Sources: Optionally, your environment might include multiple data sources needed by your initiative, such as other relational sources, Essbase, Hyperion Financial Management, Microsoft Analysis Services, SAP B/W, and others. These sources can be shared or dedicated, local or remote.

    • Connectivity: You must set up connectivity from your Administration Tool and Oracle Business Intelligence stack to each data source. This configuration can include installing the required drivers or clients, setting up ODBC DSNs, setting up native connectivity, and other steps. See Chapter 5, "Importing Metadata and Working with Data Sources" and Chapter 16, "Setting Up Data Sources on Linux and UNIX" for full information.

      Note that for Oracle Database connectivity, Oracle Business Intelligence requires an instance of TNSnames.ora in ORACLE_HOME/network/admin.

Figure A-5 shows the architecture of the multiuser development sandbox.

Figure A-5 Multiuser Development Sandbox Architecture

Description of Figure A-5 follows
Description of "Figure A-5 Multiuser Development Sandbox Architecture"


Most developers prefer to disable caching in the development sandbox. This makes it easier to validate and debug physical queries using the log. When the cache is enabled, the physical SQL might not appear in the log, because the request might get fulfilled by the cache. In this release, you must disable caching using Fusion Middleware Control. See "Using Fusion Middleware Control to Enable and Disable Query Caching" in Oracle Fusion Middleware System Administrator's Guide for Oracle Business Intelligence Enterprise Edition for more information.

Multiuser Development and Lifecycle Management Architecture

The overall MUD architecture contains the developer sandbox systems described in the previous section, as well as any test and production systems. In addition, there are several additional major components, as follows:

  • Windows MUD administration system. This system is maintained by the MUD administrator. Note the following about this system:

    • It provides one shared network MUD directory for the main branch, and additional shared network MUD directories for each side branch. The Windows permissions on each shared directory only allow access to the developers for that branch. Each shared directory stores the master repository for that branch, as well as various control and history files for MUD functions.

    • It has a client installation of Oracle Business Intelligence. The Administration Tool and Oracle BI Server utilities are used for creating and managing MUD projects, performing merges, creating patches, and other MUD administrator tasks. Other Oracle Business Intelligence processes like the Oracle BI Server, as well as the policy store and credential store, are typically not used on this platform.

    • A 32 bit or 64 bit system can be used, because none of the Oracle Business Intelligence Java components, system components, or other infrastructure are used on this computer.

  • One or more test systems. These systems are used for running integrated tests of merged content. They run the full Oracle Business Intelligence stack, and can be either UNIX- or Windows-based. These systems are frequently clustered.

  • Oracle BI Presentation Catalog system. Optionally, you might have a system with a full Oracle Business Intelligence stack for developing Oracle BI Presentation Catalog content.

  • Clustered production system. Eventually, you will have a clustered production system on one of the supported Oracle Business Intelligence platforms.

  • External identity store. This appendix assumes you are using an external identity store like Oracle Internet Directory.

Figure A-6 shows a sample deployment architecture for the repository lifecycle using the multiuser development environment.

Figure A-6 Example Multiuser Development Deployment Architecture

Description of Figure A-6 follows
Description of "Figure A-6 Example Multiuser Development Deployment Architecture"

Understanding the Multiuser Development Environment

MUD is a set of features that enables teams of developers to work in parallel on projects of any size, despite the complex interrelationships and dependencies in the repository model. With MUD, you can:

The multiuser development feature also provides the following other useful capabilities:

This section contains the following topics:

About Multiuser Development Environment Task Flow

The basic flow of working with multiple users is as follows:

  1. A developer defines the "starter" Physical layer, as well as basic facts and subject areas. This provides some basic objects to anchor the MUD projects.

  2. The MUD administrator defines projects and puts the RPD into the main branch MUD directory. Note that the MUD directory where the master repository is stored cannot be the same as the Oracle BI Server local repository directory.

  3. A developer can now check out one or more projects, do development work, and then merge the changes into the master by publishing to the MUD directory.

  4. Meanwhile, other developers check out and do development on the same or other projects (note that projects are for subsetting, not for enforcing security). Because the publishing step uses a three-way merge, users can check out, develop, and publish their changes in any order. Even property changes to a single object from multiple users are merged. If conflicts do occur between users, the three-way merge feature provides a way for the developer to choose which objects to keep. Communication between users is a key to avoiding and resolving conflicts, and you should have your governance process assign ownership of major objects in order to avoid such conflicts.

  5. When a development phase is complete, the MUD administrator can migrate the content to a test system. There might be several iterations back through check out, bug fix, publish, and retest. When the repository passes the testing phase, the MUD administrator can migrate it to the production environment.

  6. The MUD administrator can create and manage multiple development branches as large MUD projects. A branch can be secured to ensure that only one development team can work on it. A branch can even be treated recursively as a main, with its own, delegated MUD administrator.

About Multiuser Development Projects

The multiuser development feature is built around a metadata object called a project. The project is the unit of check-out from the master repository, and the subsequent merge and publish. When a master repository becomes very large, a project is a manageable-sized subset that a developer can check out to work on. It is also designed to be self-consistent, so that you can run the consistency checker (analogous to compile-time code checking) and then test it on the Oracle BI Server with a client such as Answers at run time. When you are satisfied with the results, you can merge it back into the master repository so that it becomes part of the larger application. Meanwhile, history is logged and repository backups are automatically created at key points.

MUD features in the Administration Tool streamline this flow for fine-grained developer projects. Similarly, superset projects streamline the management and merging of branches.

The project subset contains a set of metadata objects. You define a project to include a minimum set of objects explicitly, but many others are included implicitly. Having objects implicitly added to projects simplifies your project management task.

The following objects are explicitly specified by the MUD administrator as members of a project:

  • Logical fact tables

  • Presentation layer subject areas

  • Application roles

  • Users (although the best practice is to only use application roles in RPD logic)

  • Initialization blocks

  • Variables

All other objects are implicitly included in a project and are found by the Administration Tool during the check-out process. For example:

  • Descendents of the explicitly defined objects. For example, when a logical fact table is included explicitly, all its logical columns are included in the project implicitly.

  • Logical dimension tables that join to the selected logical fact tables, and the join objects themselves.

  • Logical table sources for the included logical fact and dimension tables.

  • Physical tables that map to the logical tables included in the project, and the joins between them.

  • Marketing target levels and list catalogs.

Note that objects that are in the list of explicitly defined objects are sometimes included implicitly. For example, if a logical column contains an expression that includes a variable, the variable is implicitly included in the project, even if the MUD administrator does not explicitly add it.

It is normal for projects to overlap. An object that appears in one project can also appear in another project. For example, some customers prefer to create an overall project for each independent semantic model, as well as smaller projects within each independent model for checking out individual units of development work. You can also check out multiple projects simultaneously to work on a larger set of metadata.

See also "Setting Up Projects" for additional information.

How to Create Branches

This section explains how to create main branches, side branches, and delegated administration branches.

This section contains the following topics:

How to Create a Main Branch

The ultimate master repository is usually source-controlled in the main branch, out of which all branches and ultimately all development projects check out. The main branch usually stages the repository in production. That is, to migrate content to production, you merge it into the main branch, and then migrate the main repository to the production system.

Similarly, to fix a production bug, a developer typically checks out of the main branch. The developer then fixes the bug, and then merges it back into the main branch for migration to test and production. Meanwhile, parallel development in side branches is not affected.

To create the main branch as the MUD administrator, you must first create a shared directory and copy the master repository file to it. The directory can be on either Windows or UNIX, but the UNIX share must be accessible by Windows users.

Set the security on the share to only allow access by the appropriate developers. Depending on your requirements, you might only allow developers to access the side branch master repositories, not the main branch master repository.

If this is a new project, you typically have a developer seed the repository with initial content that can be easily split into branch projects.

How to Create a Side Branch

The best practice for branching is to start with a superset MUD project, and then use the MUD check-out, merge, and publish features. Then, individual users or sub-branches use finer-grained projects and check out of the branch master. Using MUD for this functionality provides automatic back-ups at the check-out points, tracks original repositories to ensure correct merges, uses more optimistic merge assumptions that require less user intervention, and provides history and roll-backs.

To create a side branch as the MUD administrator:

  1. In the main master repository, create a project that extracts all content required for the branch. Follow these guidelines to create the project:

    • If little or no metadata has been designed in the repository, it is a best practice to seed it with content that can anchor the project. This makes it easier to ensure the project extracts the physical content you need to support the logical fact tables. Usually, this means one or more logical fact tables are created, with at least some representative columns. The columns should be mapped to the physical tables and joins needed to support the fact tables. Finally, create the project and define the objects that belong to it.

    • If content already exists, create the project and define the objects needed in that branch. The branch can overlap with other projects, if necessary.

    • It is also possible to create an empty project for check-out. However, the developer who checks it out must ensure that all the physical objects that need to be implicitly added to the project are mapped to the logical fact table before changes are published. Similarly, the developer must ensure dimensions are joined before changes are published to ensure their inclusion, and must explicitly add any subject areas, variables, initialization blocks, application roles, and users. This method is more prone to errors than seeding the project before defining it.

    • Typically, connection pools for environments such as production must be secured. Ensure that the connection pool settings in the master repository are acceptable for the developers to access. Note that developers typically change the settings to match their local test databases. When changes are published, connection pool and database settings are not merged, to prevent overwriting the settings in the master repository.

      Use the Oracle BI Server XML API to automate connection pool changes required during migrations to production and other environments. See "Moving from Test to Production Environments" in Oracle Fusion Middleware XML Schema Reference for Oracle Business Intelligence Enterprise Edition for more information.

  2. Create a shared MUD directory for the branch. Every branch should have its own MUD directory. Set the permissions so that only the developers working on that branch have access to it.

    Note that you can use branch permissions combined with project subsetting to prevent developers from seeing metadata that belongs to other teams. Design the projects carefully so that they only extract metadata related to one team. This goal is easiest to achieve if the teams use different business models, subject areas, physical models, variables, initialization blocks, and application roles.

    It is also a best practice to use a consistent system of naming and numbering your branches.

  3. Check out the branch project using File > Multiuser > Checkout. You can check out into your local repository directory, or another directory.

  4. Copy the repository to the branch MUD directory, where it serves as the master repository.

  5. Define fine-grained MUD projects for developers to check out from the branch. Inform the developers that the branch is ready for development.

  6. Based on your project plan, your developers perform a final merge and publish of their changes when they have completed development and unit tests.

  7. When all changes of planned content are published for the phase, the branch project is ready to undergo integrated testing. To accomplish this, migrate the branch master repository file to the test environment. When a bug is found, the assigned developer checks out the appropriate projects, fixes the bug, and tests the metadata. After the changes are published, migrate the branch repository to the test environment again. Note that this branch project can be tested without impacting, or being impacted by, development work in other branches.

  8. When integrated testing is complete, the branch is ready to promote to production. Remove the branch master repository from the branch shared directory so that users cannot change it. Copy it back into your local repository directory, and merge it into the main using the Administration Tool. The main repository is now ready for migration to integrated test and production.

  9. Typically, the MUD administrator checks out the branch again and places the branch repository in the shared MUD directory for the next phase of development. Note that during the check-out, any changes from other branches, or bug fixes from the main branch, are picked up by the branch repository.

How to Create a Delegated Administration Branch

You can use a branch to delegate local control of a metadata subset to the organization that is developing and maintaining it. To do this, you assign a branch MUD administrator to the branch, who performs the same roles as the main MUD administrator. This approach works best with an independent semantic model, so that you can ensure that there is no metadata overlapping with other groups.

The delegated branch MUD administrator performs the same tasks as the main branch administrator, including defining projects for further branches and creating fine-grained projects for developers.

To create a delegated administration branch as the main MUD administrator:

  1. Set permissions on the main MUD directory so that only the main MUD administrator (and the main MUD administrator backup) have access.

  2. Create a branch MUD project, branch MUD directory, and checked-out branch master repository as described in the previous section.

  3. Set security on the branch MUD directory so that the main MUD administrator and the delegated branch MUD administrator have access.

  4. The branch administrator defines projects for further branches, as well as fine-grained projects for developers. If required, the branch administrator deploys additional branches off the delegated branch for development initiatives, with permissions set to allow developers to check out of these repositories.

  5. Developers fix production bugs by checking out of the delegated branch MUD directories, because individual developers are not allowed access to the main branch.

  6. When developers publish all their changes, the branch administrator checks their branches into the delegated branch for integrated testing.

  7. To promote a delegated branch to production after integrated testing is complete, the main MUD administrator performs the following two steps:

    1. Removes the branch master repository from the delegated branch repository shared directory and checks it back into the main branch using the Administration Tool.

    2. Migrates the main branch master repository to production.

  8. Typically, the main MUD administrator checks out the branch again and places the branch repository in the delegated branch shared MUD directory for the next phase of development. The branch administrator then checks out next-level branches and places their repositories into the branch shared MUD directories, so that developers can check out their fine-grained projects and begin their work.

Which Merge Utility Should I Use?

There are several different merge tools that are optimized for various situations and environments. When deciding which merge approach and utility to use, you should consider whether you need to perform the task on Windows or UNIX systems. You should also consider your other requirements, such as whether you need to merge changes you made to a semantic model, or whether you need to combine two semantic models from different development efforts.

Table A-4 shows which merge approaches and tools meet various requirements.

Table A-4 Requirements Met by Different Merge Approaches

Requirement Merge Approach Tools Used Platform
  • Merge a checked-out MUD project back into master repository

  • Merge a checked-out MUD branch project back into the main branch master repository

Three-way merge

  • MUD merge


  • Combine non-MUD branches and changes back into the main branch

Three-way merge

  • Merge Repository Wizard (Full Merge selected)


  • Apply an Oracle update XML patch to customized, deployed BI Application

  • Apply an update XML patch you created from development to a deployed repository

Three-way merge

  1. Merge Repository Wizard (Patch Merge selected)

  2. Patchrpd utility

  1. Windows

  2. All

  • Combine disjoint logical content with potential ID conflicts

Two-way merge

  • Merge Repository Wizard (with blank original)


  • Combine disjoint content guaranteed in advance by the developer to have no conflicts (all platforms)


  • biserverxmlexec -B

  • biserverxmlcli (online)

  • Copy/Paste XML


  • Combine disjoint content guaranteed in advance by the developer to have no conflicts (Windows only)


  • Copy/Paste Administration Tool tool objects

  • Administration Tool Import from Repository (deprecated)


See "Merging Repositories" for more information about merging.

MUD Tips and Best Practices

This section provides tips and best practices for working in a multiuser development environment.

This section contains the following topics:

Best Practices for Branching

Follow these guidelines for creating side branches:

  • The MUD directory where the master repository is stored cannot be the same as the Oracle BI Server local repository directory.

  • A branch should be a checked-out MUD project. This automates and streamlines many of the tasks of merging the branch back into the main branch, such as using the correct original repository.

  • Always put the checked-out branch master repository into its own MUD directory. Then, let developers check out their fine-grained projects from the branch master repository. When branch development, publishing, and testing are complete, remove the master from the branch repository directory and publish it back to the main branch master repository using the Administration Tool. Then, check it out again and place the new version in the branch MUD directory for development of the next phase.

  • Use Windows permissions on the branch MUD directory to control which developers have access to it.

  • Set multiuser development options by creating an .opt file in the branch MUD directory. As a best practice, define specific administrators, and set Mandatory Consistency Check and Equalize During Merge to Yes. See "Setting Multiuser Development Options" for more information.

  • Plan your branches based on the increments of functionality you want to deliver to production. Each branch should contain an increment you want to migrate as a unit.

  • If you accidentally merge branches in the wrong order, you can roll them back using the MUD history. See "Viewing and Deleting History for Multiuser Development" for more information.

Best Practices for Setting Up Projects

Follow these guidelines for setting up projects:

  • Break your RPD down into fine-grained projects, as small as possible while still being useful. Doing so improves performance and ease of management.

  • Break your logical fact tables down into smaller partitions to enable smaller, separate projects.

  • For each side branch, overlay a larger project that will extract the branch's contents. This enables the project to manage the checkout and merge of the branch, including tracking of the original repository. Individual developers can check out their development projects from the checked-out branch project. Be sure that all development projects are published back to the side branch before merging it back into the main branch.

  • When you add new content to a repository, be sure it is part of your project before you check it in. If you create and publish objects that are not part of a project, they will not be in your extract the next time you check the project out. You or the MUD Administrator must then edit the entire repository, or at least several other projects that do happen to include your new content, and then add the objects to the project at that time.

  • Sometimes, you might need to extract several projects at the same time to get all the content you need.


Presentation layer objects, including subject areas, presentation tables, and presentation hierarchies, are now objects that you explicitly include in the project. Unlike in previous releases, the security settings of the Administration Tool user have no impact on which subject areas, presentation tables, or presentation columns are included in a project when checking it out. Instead, the set of Presentation layer objects determines the scope of the project.

See also "Setting Up Projects" for more information.

Best Practices for Three-Way Merges

Follow these guidelines when performing three-way merges:

  • Ensure that you have the original repository from which both the modified and current repositories were built.

    Note that this step is done for you automatically in a MUD merge.

  • Typically, you should open the development repository as current, then use the main repository as modified, and the starting point of the branch as original.

  • Unit test before merging.

  • As a best practice, select Equalize during merge and Check consistency of the merged RPD in the Merge Repository Wizard. See "Equalizing Objects" for full information about the importance of equalizing objects.

Best Practices for MUD Merges

Follow these guidelines when performing MUD merges:

  • Unit test before merging.

  • Unit test after merging, but before publishing. Keep in mind that you are holding the lock on the master repository, so keep it brief.

  • Be sure your full name is correct in the Tools > Options > Multiuser tab. Doing so assists in logging and in checking who holds the locks.

  • When publishing changes, be sure to write useful comments in the Lock Information screen. You or other administrators can use the comments later to help identify historical repositories when you need to perform rollbacks or other tasks.

  • When the MUD administrator is editing the master RPD, it must be inaccessible to checkout users. To accomplish this, you can temporarily remove it from the shared directory and place it in another directory, or you can rename it before editing. Make sure to restore it when the edits are complete.

    You can also open the repository in offline mode so that other users are locked out by the Windows file system. Note that you should only use this method when you are sure you will finish all your work in one atomic session.

  • Merge frequently. The list of conflicts and decisions needed in a small merge is easy to understand. When the merge is too large, the number of changes make it much harder to understand, and it is much harder to avoid human errors. If you need to roll back, the number of changes discarded is also much bigger. Performance is also better for small merges.

  • If performance of merges is a problem, consider breaking the project down into several, finer-grained projects. Also, be sure to merge more frequently, so the number of changes in the merge is smaller and therefore faster.

  • Because local connection pool changes are overridden by the connection pool settings in the master repository each time changes are published, the local test settings must be reapplied at each checkout if they are different from the master. It is best to automate application of your local connection pool settings using the Oracle BI Server XML API. See "Moving from Test to Production Environments" in Oracle Fusion Middleware XML Schema Reference for Oracle Business Intelligence Enterprise Edition for more information.

  • The most successful large teams have formal process requirements and expectations for the communications and tasks between the repository developers and the MUD administrator. For example, they might have a form for a request for the MUD administrator to create a project. Many teams also have service level agreements and lead times, such as 24 hours to create a project.

  • Set the option to force a consistency check during MUD merges. A clean consistency check ensures that the Oracle BI Server can load the model correctly, similar to the way a compiler checks to see if code can be generated correctly. Even if the merge seems to succeed, an inconsistent repository may have trouble with starting the Oracle BI Server, online repository editing check-ins, and subsequent merges. See "Setting Multiuser Development Options" for information about how to enable this feature.

  • Set the option to force an equalize before merge. This reduces the number of duplicate objects, since it is common for developers to import the same physical tables, for example. See "Setting Multiuser Development Options" for information about how to enable this feature.

    See also "Equalizing Objects" for full information about the importance of equalizing objects.

  • Do not delete or change content needed by others, unless you are the owner and have coordinated with the other developers. If you delete a column you do not need in your project, that action usually causes it to be deleted from the master when you merge, even if other users depend on it.


Presentation object aliases receive special treatment in merges. Their purpose is to hold historical names of objects, so that when names change, old reports do not break. If you changed any names during development, new aliases were added. During merge, you have the option whether to keep any new aliases you have created, or not. You also have the option to keep any or all past aliases, because the historical reports might still exist.

See also "About the Multiuser Development Merge Process" for more information.

Best Practices for Two-Way Merges

Use two-way merge when you need to combine two repositories that were developed separately into a single repository. This situation usually occurs when you need to host two semantic models in a single repository.

Follow these guidelines when performing two-way merges:

  • Make sure that the top-level objects in each repository have different names, so there are no unintentional renames or object merges. Check the following objects:

    • Business models

    • Subject areas

    • Physical databases

    • Variables

    • Initialization block

    • Application roles

    • Users

    • Marketing objects

  • Equalize before merging. Doing so honors the fully qualified names over which you have control, and assigns upgrade IDs to ensure there will be no conflicts between the two repositories. See also "Equalizing Objects" for full information about the importance of equalizing objects.

  • In the Administration Tool, perform a full merge with a blank repository as the original file.

    To create a blank repository, open a new repository, and save it without importing a source or creating any objects. Although this repository contains default security objects, these do not impact your merges.


Do not use features like Import from Repository or copy/paste in the Administration Tool to move metadata incrementally. These approaches do not correctly merge changes.

Using these features might produce the results you expect most of the time, but this is just good luck. The rest of the time, values of the upgrade IDs in the metadata objects will clash, effectively causing overwrites of random objects. However, you might not notice the problem until much later when you do regression testing. Because upgrade IDs are assigned sequentially, and are only unique within one repository, clashes are very likely.

You should also use caution when using the biserverxmlcli and biserverxmlexec -b utilities. Be sure to fully understand the information about managing IDs described in "About Using the Oracle BI Server XML API to Merge and Append Objects" in Oracle Fusion Middleware XML Schema Reference for Oracle Business Intelligence Enterprise Edition.

See also "Performing Full Repository Merges Without a Common Parent" for more information about two-way merges.

Best Practices for Production Migration

Follow these guidelines when moving from test to production:

Best Practices for Application Roles and Users

Follow these guidelines when working with application roles and users:

  • Do not build data access security around user objects in the repository. Instead, define repository permissions, filters and governors based on application roles.

  • The set of application roles should be defined by the governance committee. The business team knows what the business roles are, who is allowed to see which data, and which roles are the same from one application to the next. Therefore, the governance committee is in a position to define and name the application roles and decide which roles can be shared across applications.

  • When you create a new Application Role, be sure to add it to a project so that you can check it out again after you merge. Also, if you create a placeholder application role in the Administration Tool in offline mode, make sure to add it to the policy store later.

  • You can find whether the application roles used by a repository are provisioned in the system by opening your repository in the Administration Tool in online mode and running the consistency checker. It is recommended that you perform this check each time you migrate the repository and application roles to a new system.

  • If you only need to migrate a small number of application roles between environments, you can enter them manually in Fusion Middleware Control on the target system if you are using the embedded policy store in Oracle WebLogic Server.

Troubleshooting Multiuser Development

This section describes common problems and how to resolve them.

Orphan Lock Held on Master RPD

If a user sets a lock by issuing the command to publish changes to the network, it is not cleared until publishing is complete. If the user forgets and leaves for a two-week vacation, the MUD administrator can release the lock.

The lock is stored in a hidden system file in the master directory. If you cannot see the lock file, in Windows Explorer, select Tools, then select Folder Options. In the View menu, ensure that the option Show hidden files and folders is selected.

The lock file has the same name of the master RPD with a .lck extension. Delete the lock file to release the lock on the repository.

Figure A-7 shows a repository lock file.

Figure A-7 Repository Lock File

Description of Figure A-7 follows
Description of "Figure A-7 Repository Lock File"

Object Deleted By Other User

If another MUD developer deletes an object that you need, you can choose one of the following options:

Project Missing Needed Physical Tables and Joins After Checkout

Physical objects do not explicitly belong to a project. Instead, the physical objects mapped to the logical fact tables in your project are extracted at the time of check out.

To get needed physical objects into your local extract, check out an additional project that does have mappings to the physical objects you need. If there is no such project, then the entire repository must be edited to create mappings to a logical fact table in your project. The MUD administrator can take the repository off line to make that change. Then, your next check out should include the physical objects.

Objects Added in the Last Session Missing from Checked Out Repository

If recently added objects are missing from your checked out repository, you might have forgotten to add the objects to your project before you merged and published. Only objects in your project, or inferred from your project (like dimensions and physical objects), are included in your extracted repository.

To resolve this issue, ask the MUD administrator to add the objects to your project in the master repository, and then check out again.

Object Renamed by Appending #1

This situation occurs when two objects are merged with the same fully qualified name, but with different internal upgrade IDs. The merge logic in this situation determines that the objects are semantically different objects, and changes the name of the object to preserve uniqueness.

To resolve this issue, run the equalizerpds utility, which reassigns upgrade IDs so that objects with the same fully qualified names in the two repositories have the same Upgrade IDs. Then, try the merge again. The two objects should be merged instead of causing a rename.

See "Equalizing Objects" for more information.

Rolling Back to Previous Versions

The multiuser development environment stores backup copies of RPDs at appropriate checkpoints. Each time a potentially destructive operation is performed, a new backup is stored in the master directory. It has the name of the RPD, and the extension is a three-digit incrementing integer. Individual developers can also make copies of their RPD files at any time during development.

In the developer's sandbox, the original version of a checked-out project is stored with the name originalrpd_name.rpd. This version is automatically used if the developer discards changes.

You can also view and roll back to an older version by following these steps:

  1. Open the Administration Tool, but not a repository.

  2. Select File > Multiuser > History.

  3. Select the version of interest, and then choose Actions > View > Repository.

  4. Select File, then select Copy As to save that version to a new name.

  5. Use the older version to replace the latest version, or replace the master repository with the older version.

Example A-1 Replacing the Latest Version

This example explains how to copy an older version to replace the latest version. Assume you are at version 1000 and want to roll back to version 900. In this situation, you have three files: repository.900, repository.1000, and repository.rpd, the current version. To perform the roll back, make a copy of repository.900 and rename it to repository.1001. (This lets you keep repository.1000 in your version history.) Then, copy repository.900 to repository.rpd.

Manually Updating the Master MUD Repository

During the course of Oracle BI repository development in a Multiuser Development (MUD) environment, it might be necessary to make manual changes to the master repository. Because of the highly controlled nature of the MUD process, you need to be careful when performing any manual steps because there is accounting information stored in the MUD history log (.mhl) file. To manually work on the master repository, you must work on the repository in a separate directory from your MUD directory. Then, you must replace both the master RPD and the latest versioned repository in the MUD directory.

For example, follow these steps to manually update a repository named master.rpd:

  1. Copy the master repository (master.rpd) out of the MUD directory into a local directory.

  2. Use the Administration Tool to make the changes necessary to the local copy of the master repository (master.rpd).

  3. When manual edits are complete, copy master.rpd to the MUD directory as master.rpd. For example:

    copy c:\local\master.rpd c:\mud\master.rpd
  4. In the MUD directory, identify the latest repository with a version number. For example, master.7011.

  5. Copy master.rpd to the MUD directory and overwrite the latest versioned repository. For example:

    copy c:\local\master.rpd c:\mud\master.7011