MUD Tips and Best Practices

Best Practices for Branching

Use these guidelines for creating side branches.

The MUD directory where the master repository is stored can't 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 Model 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 Set 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 View and Delete 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's part of your project before you check it in. If you create and publish objects that aren't part of a project, they won't 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 objects that you explicitly include in the project. The security settings of the Model 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 Set Up Projects.

Best Practices for Three-Way Merges

Use these guidelines when performing three-way merges.

Ensure that you've 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 Equalize 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're 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 Oracle BI repository, 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's 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're different from the master. It's 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 Set Multiuser Development Options.
Set the option to force an equalize before merge. This reduces the number of duplicate objects, since it's common for developers to import the same physical tables, for example. See Set Multiuser Development Options.

See Equalize Objects for the importance of equalizing objects.
Don't delete or change content needed by others, unless you're the owner and have coordinated with the other developers. If you delete a column you don't 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 don't break. If you changed any names during development, new aliases were added. During merge, you've the option whether to keep any new aliases you've 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've control, and assigns upgrade IDs to ensure there are no conflicts between the two repositories. See Equalize 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 don't impact your merges.
Don't use features like Import from Repository or copy/paste in the Model Administration Tool to move metadata incrementally. These approaches don't correctly merge changes.

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.

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

See Perform 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 don't experience down time while changes are being loaded. You can use the BI Systems Management API to programmatically start and stop Oracle BI Servers, you can run the start and stop script commands (see Start and Stop Your System in Administering Oracle Analytics Server), or you can restart each Oracle BI Server manually in Fusion Middleware Control.
It isn't recommended to alter metadata in online mode in production using the Model Administration Tool.
You shouldn't 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.

Don't 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 Model 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 Model Administration Tool in online mode and running the consistency checker. It's 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're using the embedded policy store in Oracle WebLogic Server.