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 EE repository using the multiuser development environment enables you to do the following:

  • Build large, interrelated semantic models

  • Independently build multiple, independent semantic models to run in the same Oracle BI Server and Presentation Services server

  • Develop several branches on different schedules, in parallel, while fixing urgent bugs or enhancement requests on the production version

  • Incrementally design and test at the individual and team levels

  • Enable individual developers to design and test manageable subsets without impacting each other, yet share their changes with other developers in a controlled, incremental fashion

  • Migrate changes to test and production systems in bulk, or incrementally

This appendix covers the development lifecycle of the Oracle BI EE 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 Oracle Business Intelligence applications for sale as products.

See 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

Review the 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 staffed with strong business people who can negotiate effectively and make good decisions that do not change over time. Having an effective governance process is 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, road map, and requirements, as well as lower level details of the design, as described in the table below.

Task Description

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

These topics describe the hands-on roles involved in repository development and its lifecycle.

Depending on the size of your company and team, one person might perform several roles.

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 including the Administration Server, Managed Servers with Java components, and Oracle Business Intelligence system components like Oracle BI Server and Oracle BI 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

By reviewing these topics, you can get an understanding of the multiuser development environment architecture.

This section contains the following topics:

About Multiuser Development Concepts

Learn the 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. Oracle BI 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. The developers 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 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.

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. 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. See User's Guide for Oracle Business Intelligence Enterprise Edition.


The completed repository is migrated to test and production systems using Fusion Middleware Control. Downtime is not 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 -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 Administering Oracle Fusion Middleware.

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 Security Guide for Oracle Business Intelligence Enterprise Edition.

About Multiuser Development Styles

You can learn about multiuser development styles and view potential workflows or architectures.

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. The table shows the multiuser development styles.

Style Description

Serial Development

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

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

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.


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.

MUD with Multiple, Independent Semantic Models

You might need two or more independent semantic models, rather than a single, integrated, enterprise-wide model. The multiple model requirement is common resulting from 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

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.

The images shows the serial development style of multiuser development.

The image shows the shared online development style of multiuser development.

The figure shows true multiuser development with branching.

The image shows the architecture for a repository with multiple, independent semantic models.

The table shows which multiuser development styles meet various requirements for security and availability.

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






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

Each independent semantic model has its own MUD administrator






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.

You need to decide whether to use a UNIX or Windows server for Oracle Business Intelligence. You can use these guidelines:

  • If you choose the Windows-only option, make sure your system has enough memory. You 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 need a Windows system to run the Oracle BI 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:


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

You need to install a development database. You can set up the database as dedicated database, personal database, or share the database among multiple repository developers. Consider the following 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 the image that follows.

  • 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. In addition, consider the following:

    • Test Data: You should load the data source schemas with test data. If users are testing read-only metadata, You can share the schemas among multiple development sandboxes. You can put the schemas on the development sandbox computer when the computer has enough memory.

    • Multiple Sources: Your environment can support multiple data sources needed by your initiative such as other relational sources, Essbase, Hyperion Financial Management, Microsoft Analysis Services, SAP B/W, and others. You can share the data sources or put the data sources on dedicated, local or remote servers.

    • 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 Importing Metadata and Working with Data Sources and Setting Up Data Sources on Linux and UNIX.

      For Oracle Database connectivity, Oracle Business Intelligence requires an instance of TNSnames.ora in BI_DOMAIN/config/fmwconfig/bienv/core.

The image shows the architecture of the multiuser development sandbox.


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 System Administrator's Guide for Oracle Business Intelligence Enterprise Edition.

Multiuser Development and Lifecycle Management Architecture

The overall MUD architecture contains developer sandbox systems, test, and production systems.

There are several additional major components:

  • The Windows MUD administration system is maintained by the MUD administrator:

    • 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 such as the policy store and credential store are typically not used on this platform.

    • You can use a 32 bit or 64 bit system because no Oracle Business Intelligence Java components, system components, or other infrastructure are used on this computer.

  • One or more test systems

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

  • Oracle BI Presentation Catalog system

    You could have a system with a full Oracle Business Intelligence stack for developing Oracle BI Presentation Catalog content.

  • Clustered production system

    You use a clustered production system on one of the supported Oracle Business Intelligence platforms.

  • External identity store.

    Oracle assumes that you are using an external identity store such as the Oracle Internet Directory.

The image shows a sample deployment architecture for the repository lifecycle using the multiuser development environment.

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:

  • Divide the repository file into subsets

    • Enables users to work with manageable subsets when the repository is very large

    • Enables independent testing for each subset by each developer or team

    • Makes it easier to manage merges later after checking out a branch subset

    • Enables you to separate independent semantic models into secure branches for development

  • Incrementally develop, test, and migrate

  • Merge subsets and branches, handling conflicts between user changes

  • Apply Oracle updates to a packaged BI Application you have modified

  • Merge separately developed applications into a single repository

  • Access history logging and audit information

  • Roll back to historical repository states

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

  • Coordinates merging into the master, including tracking original repository files

  • Provides locking for reliable updates

  • Logs changes

  • Automatically backs up repositories before each potentially destructive operation

This section contains the following topics:

About Multiuser Development Environment Task Flow

Learn the basics for working with multiple users in a development environment.

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

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

  • The MUD administrator defines projects and puts the repository (RPD) into the main branch MUD directory.


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

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

  • Other developers check out and do development on the same or other projects. Use projects to create subsets of the development work and not as a tool 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.

  • 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.

  • 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, use a project is a manageable subset that a developer can check out to work on. Projects are self-consistent, so that you can run the consistency checker against the project and then test the project on the Oracle BI Server with a client such as Oracle BI Answers at run time. When you are satisfied with the results, you can merge the project into the master repository so that the project becomes part of the larger application. History is logged and repository backups are automatically created at key points.

The MUD features in the Administration Tool streamline the flow for fine-grained developer projects. 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

    The best practice is to assign users to application roles in repository (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.

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 Setting Up Projects.

How to Create Branches

Learn how to create main branches, side branches, and delegated administration branches.

This section contains the following topics:

How to Create a Main Branch

The master repository is usually source-controlled in the main branch, out of which all branches and all development projects check out.

The main branch can stage the repository in production. To migrate content to production, you merge it into the main branch, and then migrate the main repository to the production system.

To fix a production bug, a developer should check out the source from the main branch. The developer then fixes the bug, and then merges it back into the main branch for migration to test and production. The 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 the shared directory. You can use Windows or UNIX for the directory and make the UNIX share 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, a developer needs to populate the repository with initial content to 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. Individual users or sub-branches can use the 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.

Follow these guidelines to create the project:

  • If little or no metadata has been designed in the repository, the best practice is to add content that can anchor the project. Adding content makes it easier to ensure the project extracts the physical content you need to support the logical fact tables. You should create one or more logical fact tables with some representative columns. Map the columns 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.

  • You must secure connection pools for environments such as your production environment. Verify that the connection pool settings in the master repository are acceptable for the developers to access. Developers can 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 XML Schema Reference for Oracle Business Intelligence Enterprise Edition.

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

  • You can use branch permissions combined with project subsets 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.

Perform integrated testing on the branch:

When all changes of planned content are published for the phase, the branch project is ready to undergo integrated testing. 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. Developers can test the branch project without impacting, or being impacted by, development work in other branches.

  1. In the main master repository, create a project that extracts all content required for the branch.
  2. Create a shared MUD directory for the branch.
  3. From File, select Multiuser , and then select Checkout to a 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. Test the branch.
  8. Remove the branch master repository from the branch shared directory so that users cannot change it and 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. The MUD administrator checks out the branch again and places the branch repository in the shared MUD directory for the next phase of development. 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.

  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.


When using Oracle BI EE tools such as nqcmd, biserverxmlcli, and comparerpd, you must edit the input to match the format expected by SQL, for example, do not include a single quote in your XML content.

The table shows which merge approaches and tools meet various requirements.

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

In the Merge Repository Wizard use Full Merge.


  • 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

In the Merge Repository Wizard with Patch Merge selected use the Patchrpd utility.

  • Windows

  • All

  • Combine disjoint logical content with potential ID conflicts

Two-way merge

In the Merge Repository Wizard select 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.

MUD Tips and Best Practices

Learn tips and best practices for working in a multiuser development environment.

This section contains the following topics:

Best Practices for Branching

Use 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.

  • 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.

Best Practices for Setting Up Projects

Use these guidelines for setting up projects.

  • Break your repository building into fine-grained projects that are as small as possible while still useful to improve 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 to 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 Setting Up Projects.

Best Practices for Three-Way Merges

Use these guidelines when performing three-way merges.

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

  • 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.

Best Practices for MUD Merges

Use 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.

  • Verify that your full name is correct in the 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 repository (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 open the repository in offline mode to avoid locking users out by the Windows file system. You should only use this method when you can finish all work in one 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. Merge frequently, so the number of changes in each merge is smaller and 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 XML Schema Reference for Oracle Business Intelligence Enterprise Edition.

  • 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.

  • 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.

    See Equalizing Objects for 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 About the Multiuser Development Merge Process.

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 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 XML Schema Reference for Oracle Business Intelligence Enterprise Edition.

See Performing Full Repository Merges Without a Common Parent.

Best Practices for Production Migration

Use these guidelines when moving from test to production.

  • When updating metadata on the production cluster, perform a rolling restart to restart one Oracle BI Server at a time, so that users do not experience down time while changes are being loaded. You can use the BI Systems Management API to programmatically start and stop Oracle BI Servers, or you can restart each Oracle BI Server manually in Fusion Middleware Control.

  • It is not recommended to alter metadata in online mode in production using the Oracle BI Administration Tool.

  • You should not update metadata in online mode in production using the biserverxmlcli utility.

Best Practices for Application Roles and Users

Use 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

These are some common problems and how to resolve them in this section.

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.

The image shows a 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:

  • Roll back to an earlier version, and reapply all the changes since then. The easiest way to roll back is generally to replay history in the history log. To rollback changes, choose File, select Multiuser, and then select History. Select an entry, use Actions, and select View.

    See Viewing and Deleting History for Multiuser Development.

  • Re-create the deleted objects, and equalize so that future merges treat it as the same object.

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.

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 Oracle BI Server, but not a repository.

  2. From the File menu, select Multiuser, and then select History.

  3. Select the version of interest, choose Actions, select View, and then select 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.

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 Oracle BI Server 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

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.