Understand 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've 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 Oracle BI repository (RPD) into the main branch MUD directory.

The MUD directory where the master repository is stored can't 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 Answers at run time. When you're 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 Model 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 Oracle BI repository logic.
Initialization blocks
Variables

All other objects are implicitly included in a project and are found by the Model 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 doesn'texplicitly add it.

It's 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 Set 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 isn't 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 Linux for the directory and make the Linux share available 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's 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 aren't 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's 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.

In the main master repository, create a project that extracts all content required for the branch.
Create a shared MUD directory for the branch.
From File, select Multiuser , and then select Checkout to a local repository directory, or another directory.
Copy the repository to the branch MUD directory, where it serves as the master repository.
Define fine-grained MUD projects for developers to check out from the branch. Inform the developers that the branch is ready for development.
Based on your project plan, your developers perform a final merge and publish of their changes when they have completed development and unit tests.
Test the branch.
Remove the branch master repository from the branch shared directory so that users can't change it and copy it back into your local repository directory, and merge it into the main using the Model Administration Tool. The main repository is now ready for migration to integrated test and production.
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's 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.

Set permissions on the main MUD directory so that only the main MUD administrator, and the main MUD administrator backup, have access.
Create a branch MUD project, branch MUD directory, and checked-out branch master repository as described in the previous section.
Set security on the branch MUD directory so that the main MUD administrator and the delegated branch MUD administrator have access.
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.
Developers fix production bugs by checking out of the delegated branch MUD directories, because individual developers aren't allowed access to the main branch.
When developers publish all their changes, the branch administrator checks their branches into the delegated branch for integrated testing.
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 Model Administration Tool.
2. Migrates the main branch master repository to production.
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, consider the platform on which you must perform the task. 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.

Important:

When using tools such as nqcmd, biserverxmlcli, and comparerpd, you must edit the input to match the format expected by SQL, for example, don't 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	Windows
Combine non-MUD branches and changes back into the main branch	Three-way merge	In the Merge Repository Wizard use Full Merge.	Windows
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.	Windows
Combine disjoint content guaranteed in advance by the developer to have no conflicts (all platforms)	Insert-Update-Delete	`biserverxmlexec -B` `biserverxmlcli` (online) Copy/Paste XML	All
Combine disjoint content guaranteed in advance by the developer to have no conflicts (Windows only)	Insert-Update-Delete	Copy/Paste Model Administration Tool tool objects Model Administration Tool Import from Repository (deprecated)	Windows

See Merge Repositories.