Phase I - Initiating Multiuser Development (MUD)

In the first phase of the fictional company example, both Sally Andre and Scott Baker develop in parallel.

Sally creates the starter content, that Adam Straight divides into projects. He will then create the MUD directory so that Sally and Scott can check out and perform their development. After unit testing, they merge and publish their changes, and then Adam migrates the repository to the test environment. After a bug fix cycle, Adam promotes the repository to production.

The following sections describe Phase I development:

Starting Initiative S

In the fictional MUD project, Sally Andre starts off Initiative S from an empty RPD.

Because it is easier to divide the repository into MUD projects if you define some logical stars and subject areas first, she begins by developing the physical model needed for Phase I. She includes connection pool details for her own local test data sources.


The physical model should include the physical tables, the best practice of aliasing all the physical tables to give them meaningful names, and joins.

The image shows the physical model for Initiative S.

Sally drags the Physical layer to the Business Model and Mapping layer to create some starter content. She removes unneeded tables, and ensures that the star joins are correct. She also ensures that all the physical tables that will be needed during development have mappings from the starter logical tables, so that they will be included in the projects when they are checked out. For Sally, these steps create two logical fact tables, F10 Revenue and F50 Quotas, that can act as the basis for the projects.

Sally also needs to have some subject areas to map to the projects in the business model. She could drag the entire business model, but a convenient way to accomplish this is to instead right-click the business model and select Create Subject Areas for Logical Stars and Snowflakes. This feature creates a subject area from each logical fact table.

Sally does not need to be concerned about the contents of the subject areas yet. All that matters is that each subject area maps to the logical fact table for the same project. However, she does name the subject areas based on the plan agreed to in the governance meeting: Sales Quota and Sales Revenue.

Sally now has enough content for the MUD administrator to create the first two projects based on the Revenue and Quota fact tables. To review, Sally has made sure that she meets the following criteria at a minimum:

  1. At least one logical fact table according to the governance plan, to anchor the projects. The columns of the logical fact tables need not be complete or even properly named, but they do need to be complete enough to map all the physical content.
  2. Enough logical dimensions so that the repository will pass the consistency check.
  3. Physical content that maps to one or more logical fact tables, so they will be included in projects.
  4. The subject areas needed according to the governance plan.

Setting Up MUD Projects

In the fictional company example, the MUD administrator for Eden Corporation, Adam Straight, now handles the next few steps to create the projects and get them ready for checkout.

Adam Straight creates the MUD directory,RPD_main, where the master RPD is stored. This master RPD contains the superset of content for the developers. The users check their projects out of the master, and merge their project back into the master when they want to share their changes. Sally copies her started RPD to the master folder so that Adam can create the first two projects, ProjRevenue and ProjQuota.

Adam opens the master RPD in the System Administrator's Guide for Oracle Business Intelligence Enterprise Edition and selects Manage > Projects. Then, in the Project Manager, he selects Action > New Project. Adam names the project ProjRevenue and proceeds to pick the logical fact tables at the center of the project. The top object in the list expands to show the logical fact tables, but he has a choice of seeing them grouped by the Business Model to which they belong, or by Subject Area.

The image shows the different ways Adam can view the logical fact tables.

Adam decides to group facts by Business Model for convenience, although he could have used the Subject Area grouping to select the same fact table. He adds the fact table, plus the default application roles and subject areas specified for this project. Because there are no custom-defined application roles, users, variables, or initialization blocks yet, he cannot yet add them to the project. Adam repeats this process for ProjQuota, the second project.


Some of the explicit objects are the same in both projects, because both projects share application roles. Similarly, many of the implicit project objects are shared, particularly dimension tables in both the logical and physical models. Projects are a convenience for creating small subsets that are easy to work with. Project are not for security. It is critical in your governance process that the owner of each top-level object is assigned and documented for the whole team, because this enables developers to avoid conflicts.

Adam included the logical fact table F10 Bill Rev in the project, even though it is owned by Sally Andre, not by Scott Baker, the owner of this project. He did this because Scott needs to create a measure that derives from measures in both fact tables, Sales percent of quota. Again, the point is to provide the user with the subset of content they need to implement their requirements, not just the objects they own.

Adam saves the master RPD to the shared drive, RPD_Main, as sales.rpd. It is now ready for users to check out projects and begin working in parallel.

First Developer Checks Out

An administrator configures their Administration Tool clients for the master repository, check out their projects, and begin working.

The developer, Sally starts by setting up her Administration Tool client to use the master repository. She selects Tools > Options, and then selects the Multiuser tab. She sets up the pointer to the master repository directory in the Multiuser tab. She also enters her full name, used in logs and locks. She checks out her project and begins work.

In the Master Repository directory, two new files have been created the sales.000 and sales.mhl files. The image shows the new files.

The sales.000 file is an automatic backup created for sales.rpd file that was created when Sally checked out the repository. The backup file is used if a roll back is needed resulting from a problem. The sales.mhl file tracks her checkout status and parameters, including project, computer, and user.

Three files have been created in Sally's local repository directory:

  • The originalProjRevenue.rpd file is the project subset repository at the time of checkout. The originalProjRevenue.rpd used later as the original in the three-way merge process, and also when Sally discards her changes.

  • The ProjRevenue.rpd file contains only the self-consistent subset project, ProjRevenue. The ProjRevenue.rpd file that is open for editing.

  • The ProjRevenue.rpd.Log file is the log file for the editing session in the Administration Tool. You can view ProjRevenue.rpd.Log files contents in the Administration Tool using File > Multiuser > History.

    The image shows the three files in the local repository directory.

Sally begins to work on the model for her application in offline mode. She does not need to change her connection pool settings because she used her own test data source connection pool details when she created the starter content.

Sally starts by opening her fact table and deleting the unused keys based on the modeling best practice. Then, she adds SUM aggregation rules to three measures, Discnt_Value, Revenue, and Units. She also changes the name of Discnt_Value to Discount Amount, Units to Units Sold, and Revenue to Sales Revenue.

Sally also needs to add a new column to the D10 Product table, an upper-case version of the Prod_Dsc column called PRODUCT DESCRIPTION. The column uses the following expression: Upper("Sales"."D10 Product (Dynamic Table)"."Prod_Dsc"). Sally adds dimension hierarchies, creates a variable called Constant One, and initializes it to the value 1. She uses the variable to create a new measure, Constant One. Finally, she saves her work.

Sally starts her sandbox Oracle Business Intelligence stack so that she can add application roles, and then test her repository using Answers. She follows these steps to start her components in the right order and to configure her system environment:

  1. Start the database containing the RCU schema, using its standard controls. This database is the local sandbox developer database.

  2. Start the sandbox Oracle WebLogic Server Administration Server. For example, on Windows, select Start > Programs > Oracle WebLogic > User Projects > bifoundation_domain > Start Admin Server for WebLogic Server Domain and enter the user and password created during installation when prompted.


    If you used an Enterprise or Software-Only install type, you must also start the Oracle WebLogic Server Managed Server using the Oracle WebLogic Server Administration Console. Typically, you use the Simple install type when installing development sandboxes.

  3. Log in to the local sandbox Fusion Middleware Control and upload the repository file, making sure to enter the correct repository password. You upload the local subset repository, in Sally's case, the MUD checked-out repository, ProjRevenue.rpd, not the master repository.

  4. Also in Fusion Middleware Control, turn off Oracle BI Server caching, so that interpreting the query log is simpler.

  5. Still in Fusion Middleware Control, start the system components from the Business Intelligence Overview page.

    See the System Administrator's Guide for Oracle Business Intelligence Enterprise Edition provides more information about steps 2 - 5.

Because Sally's Oracle BI Server is on a Linux system, she must set up ODBC connectivity on her Windows computer so that her Administration Tool client can access the Oracle BI Server there.

Sally manually adds an Oracle BI Server ODBC DSN pointing to the Oracle BI Server on the Linux computer. See “Integrating Other Clients with Oracle Business Intelligence” in Integrator's Guide for Oracle Business Intelligence Enterprise Edition for information about how to create an ODBC DSN for the Oracle BI Server.

Sally is using the Oracle WebLogic Server embedded policy store and needs to add two application roles, Sales Management and Sales Rep. To add the roles, she opens a Web browser on her Windows computer and logs in to Fusion Middleware Control, pointing to her Oracle Business Intelligence stack on Linux. She uses Fusion Middleware Control to create the new roles, maps it to the appropriate users, groups, or other roles, and grants the appropriate permissions to the role.


See Creating Application Roles in Security Guide for Oracle Business Intelligence Enterprise Edition .

Sally needs to add the new application roles to her repository, and then use them for object permissions and data access filters. Sally uses the following steps:

  1. Sally opens the Administration Tool and selects File > Open > Online. She picks the local Windows ODBC DSN that connects to her local Oracle Business Intelligence stack, enters her repository password, and also enters the default user name and password for administering her stack that she created upon install.
  2. Next, Sally selects Manage, and then selects Identity to open the Identity Manager. She clicks BI Repository in the navigation tree and then clicks the Application Roles tab. She sees the five default application roles, as well as the new ones she just created.
  3. Sally double-clicks the Sales Rep application role, and then clicks Permissions. On the Data Filters tab, she adds a data filter with an expression that only allows users who belong to this role to see sales that they themselves have made. On the Object Permissions tab, she sets Read, Read/Write, or No Access permissions that allow Sales Rep users to see revenue, but not quota or cost information. On the Query Limits tab, she keeps the defaults for Max Rows and Max Time, and does not set any time restrictions. She clicks OK to return to the Identity Manager.
  4. Next, Sally double-clicks the Sales Management application role and sets up Data Filters, Object Permissions, and Query Limits appropriate for this role, based on the decisions of the governance committee.
  5. Finally, Sally exits the Identity Manager.
  6. Sally commits the changes she made in online mode by using the Check In Changes menu option. This action propagates the online mode changes to her local subset, ProjRevenue.rpd, but does not commit them to the master MUD repository. Sally publishes her changes to the master repository in a later step.

For the new variable and application roles to be in Sally's project the next time she checks it out, she must add them to the project before she checks in her changes. To do this, she performs the same steps that Adam did when he created the projects: She selects Manage > Projects, selects her project, selects the new objects in the left pane, and clicks Add.

Second Developer Checks Out

In the fictional company example, Sally Andre is working on the ProjRevenue project and Scott Baker is getting started on ProjQuota.

Scott sets up his Administration Tool options for MUD, checks out his project, and starts working.

Scott prefers to work in online mode. Doing this tightens the development/unit test loop, because he is modifying the repository while it is running in the Oracle BI Server. Every time he clicks Check In Changes in the Administration Tool, his changes are applied to the running server. He can then immediately move to Oracle BI Answers and test the changes there. When he adds, deletes, renames, or reorganizes Presentation layer objects, he must reload metadata in the Answers criteria tab to refresh the tree visible there.

Scott starts his local Oracle Business Intelligence stack, and uploads his checked-out subset repository. He restarts the Oracle BI Server, opens the Administration Tool, and opens his repository in online mode.

Scott must change the connection pool settings to point to his local test database, because the master repository contains Sally's settings. In the merge process, these connection pool changes are overridden by the connection pools already in the master repository. The next time Scott checks out, he needs to apply his local test connection pool changes again.


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.

Scott's next task is to clean up his logical fact table by removing keys. He also gives a measure a SUM aggregation rule and a business-friendly name, Quota Amount.

Scott does not change anything in the F10 logical table because it is owned by Sally. After she merges and publishes her changes to the master RPD, he does the same. Scott checks out again, picking up Sally’s changes.

Scott adds a new measure called Sales percent of quota to the F50 table. The measure derives from both fact tables with the following expression:

"Sales"."F10 Billed Rev."."Revenue" / "Sales"."F50 Facts Quotas"."Quota Amount"

Even if Sally changes the name of Revenue in her project, the merge identifies it as the same object and uses the new name in Scott's expression. The merge logic can identify the name change because the upgrade ID of the object is the same as the original.

Scott forgets what he learned in the Governance Committee meeting, that all the dimensions are owned by Sally. He has a requirement for an all-capitals version of the D10 Product.Prod_Dsc column called PRODUCT DESCRIPTION. He creates a column identical to the one Sally created. This mistake will be detected and resolved through the merge process during the publishing step in a few moments.

Scott does not need to upload his repository and restart his system because he is working in online mode. Instead, he unit tests his work immediately after committing his changes using Check In Changes. Meanwhile, Sally has finished testing her changes.

First Developer Publishes Changes to the Master MUD Repository

Sally has finished creating and unit testing her first batch of changes, so she saves her work and prepares to merge it into the master repository.

She chooses File > Multiuser > Publish to Network. If she forgot to add any new objects to a project, a detailed warning is displayed so that she can add the objects to her project and try the merge again. Otherwise, the objects are not extracted the next time she checks out the project.

Next, the Administration Tool locks the master repository so that Sally can merge her changes without any chance of corruption from other users' merges.


For logging purposes, it is a best practice to use the comment field to provide a description of the changes you are publishing. Publishing frequently, or performing a subset refresh, also makes it easier to keep track of changes, and easier to audit the history later. Finally, it is a best practice in Administration Tool modeling to work incrementally, which simplifies testing and reduces the complexity of each task.

Sally's changes cause no conflicts, so they do not appear in the Define Merge Strategy step that is displayed next. However, aliases for presentation objects are a special case where you can choose to keep either the modified (your local version) or current (the master), or merge the two. The aliases were automatically created when Sally changed the column names, so that reports written to the old names would not break when she put the new names into production. Because Eden Corporation has no reports yet, Sally keeps the aliases empty by selecting Current. She does this for "Sales Revenue," "Units Sold," and "Discount Amount."


Sometimes, there can be a series of aliases if names change more than once. Because there might be a set of reports using the older names, you can select Merge Choices in the Define Merge Strategy screen to keep any aliases already in Current as well as the new ones in Modified.

When the merge step is complete, the master sales.rpd is overwritten with the changes from Sally. A merge log is also stored.

Second Developer Publishes Changes to the Master MUD Repository

In the fictional company example, Scott has completed his development work for this phase, he selects File > Multiuser > Refresh Subset to perform a subset refresh to merge his changes with the latest version of the master repository.

The Define Merge Strategy screen asks whether to keep the alias created on the presentation column "Quota Amount." Like Sally, Scott chooses to keep the current repository value, which does not use the alias.

After the subset refresh, Scott unit tests again briefly. Upon inspection, he also notices his mistake of creating the same PRODUCT DESCRIPTION column that Sally did. Because Scott's column was created separately, its internal upgrade ID is different than the one in Sally's. Therefore, even though the name is the same, the merge logic knows it is a different column, and renames it rather than overwriting it by appending #1 (PRODUCT DESCRIPTION#1).

Scott deletes the extra column, connects his logic to Sally's PRODUCT DESCRIPTION column, tests again briefly, and publishes his changes to the network master repository.

Note that if Scott had deleted or modified a different user's object, the error might have been more difficult to resolve. It might have required re-creating and equalizing the object, or rolling back to a backup version of the repository and re-creating his own changes.

MUD Administrator Test Migration Activities

To prepare the repository for the test environment, the MUD administrator, Adam Straight, must now perform several tasks directly on the master repository.

He will use File > Open > Offline.

Adam begins by opening the Administration Tool and then opening sales.rpd in offline mode. As soon as he does this, other users are locked out, and will get Windows permissions errors if they try to check out projects. If Adam needed to open and close the file several times, he would need to remove the RPD from the shared directory while modifying it elsewhere, so that other users would not be able to check out between his changes.

Adam changes the connection pool settings to match the test environment. Note that when Administration Tool users check out projects, connection pool parameters are not included in the checkout. Usually, the master repository in the MUD directory contains the test connection pools, but each individual developer might need different settings for connecting to their own test databases. At merge and publish, the connection pools in the master repository are not overwritten by developer changes, so that they can continue to point at the shared test databases.

Adam must also ensure that the new application roles are migrated to the test system. Because there are only two, he decides to reenter them in Fusion Middleware Control on the test system. Adam also provisions some test users or groups to the new application roles so the security filters, permissions, and query limits can be tested.

Finally, Adam uploads the repository to the test system and restarts the Oracle BI Server. Using his local Administration Tool, he connects to the test Oracle BI Server in online mode and runs the consistency checker. If any application roles referenced by this repository are missing or incorrect, the consistency checker will list errors for them.

Phase I Testing

Learn about testing in a multiuser development environment by reviewing fictional company example.

The test team can now test the repository. During testing, the test team discovers a bug: "Sales"."F50 Facts Quotas"."Sales percent of quota" was erroneously created with the expression quota/sales instead of sales/quota. The test team writes a bug report, and Scott Baker is assigned to fix the bug.

Scott opens the Administration Tool, checks out ProjQuota, makes the change, changes the connection pool to point to his local test database, and tests on his own sandbox. Then he publishes the changes to the shared MUD directory. He informs Adam that the bug is fixed and that the repository is ready for him to send to test again.

Adam notes that the connection pools are still pointed at the correct test system, because the MUD feature isolates the master repository from connection pool changes in checked out projects. Adam uploads the repository, and restarts the Oracle BI Server.

The test team tests to completion, and the repository is cleared for production.

Phase I Migration to Production

After the repository has passed the testing phase, you must update the repository’s database connection parameters before uploading the repository to production.

You must also migrate and provision the application roles.

Based on the plan provided by the governance team, the production operations team knows the new application roles needed. They create them as Adam did for the test environment. They also provision users or groups to those application roles, based on the security specification from the governance team.

Before migrating to production, Adam has to change the connection pool parameters to the values needed for the production database. In Eden Corporation, Adam has the privilege to see the production connection pools, but the repository developers do not. Therefore, Adam cannot change from the test to production connection pools and leave the repository in the master directory, because the developers have Windows permissions to read and write to it. Instead, he creates an XML patch of the connection pools needed for Production. Then, he copies sales.rpd to a secure directory and applies the patch, and then tests to be sure it really does connect to the production data sources. He then uploads the repository to the production system, and starts the production cluster of servers.


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

Because the master repository still points to the test databases, the Administration Tool users can still be allowed to see it. Meanwhile, new versions of the production repository can be built at any time by applying the connection pool changes in the XML patch file.

Production validations are now performed. Similar to the migration to the test system, an important validation is to run the consistency checker in online mode to ensure that the application roles are all correct. When this validation is complete, Phase I is in production.

Phase I Summary

The image shows the parallel activities for Phase I for the fictional company example.