Lifecycle Management (LCM) is a fairly new concept for many administrators and developers of Oracle BI. All core transferable objects in a software application such as Oracle BI are defined as artifacts. Artifacts for Oracle BI 12c are items such as the RPD, Presentation (Web) Catalog, and so on. Since these are a few of the most critical artifacts to the operation of Oracle BI, this section discusses how they are managed in Oracle BI 12c.
LCM includes the many different areas of patching, backup, and recovery, and the general migration of Oracle BI artifacts from one environment to another. In Oracle BI 12c, there has been a concentrated effort to increase the ability to deliver a consistent, manageable Oracle BI application through the use of programmatic capability. In Oracle BI 12c, there are now several options to do so: Application Programming Interface Web Services via SOAP and REST, and Command Line Interfaces (CLI) through the Oracle BI 12c BI Tools.
The BI Tools are located in <ORACLE_HOME>user_projectsdomainsiitoolsin. These tools are available on the fully installed Oracle BI 12c server installation.
When a developer installs the Oracle BI 12c client tools on their workstation, not where the Oracle BI server is not installed, they will have access to some basic programmatic client tools but only a portion of the tools provided with the full Oracle BI 12c server installation:
The Oracle BI Client Tools, when installed, are available from a similar folder path location, <CLIENT TOOLS HOME>iitoolsin; for example, C:OracleBIClient1221iitoolsin.
One of the critical objects in the Oracle BI 12c LCM process is the BI Archive (BAR) file. This file type was introduced in the Oracle BI Cloud Service (BICS) solution prior to its release for the on-premise Oracle BI 12c solution. It operates on the similar principal of having one file to contain security information, the RPD file, and the Web Catalog files, for a compartmentalized way to move the critical artifacts of one Oracle BI environment to another.
All the exercises in this section will be done from the command prompt (Terminal window) on the server where the full version of Oracle BI 12c has been installed. After installing the Oracle BI 12c, the Sample Sales Lite subject area and respective RPD are deployed automatically to the Oracle BI server. As a developer, you would seek to make changes to the RPD and create several new reports and dashboards based on business requirements. Once the changes are made, you'll seek to migrate into the next highest level environment (for example, from Development to Testing) in order to have your changes tested, or begin in the approval process. Here you'll learn how the LCM tools will help you achieve such a goal.
The Business Intelligence Application Archive (BAR) file is a single file that contains a set of BI metadata artifacts (data model, content model, and authorization model). The general idea is that Oracle BI 12c (and BICS) maintains a service instance, and that the BAR file can be imported and exported from a single instance and transferred into another instance with relative ease. There is no data, only metadata, contained in the BAR file by default, so it is really a means to move the essential metadata required to have an operational Oracle BI portal's content deployed. Granted, a data source will still need to be referenced from the RPD of the BAR file.
During an implementation, there is often the need to either start from scratch or have a standard OBIEE interface from which to begin development efforts. Oracle BI 12c comes with a few BAR file examples once Oracle BI 12c is installed. You can find these BAR files in the following directories, below the <ORACLE_HOME> installation path; use them as a baseline when conducting your own development efforts:
..iifoundationadminprovisioningempty.bar..iifoundationsamplessampleappliteSampleAppLite.bar..iifoundationsamplesusagetrackingUsagTracking.bar
Developing in a sandbox or development environment means that you will eventually need to migrate the work you've done with the Oracle BI metadata, security, or reports and dashboard development to another environment for testing and, ultimately, to a production live environment. This section discusses the use of the BAR file for transporting artifacts during a deployment and making use of the other LCM commands for backing up and otherwise working with real-world Oracle BI.
This section will focus on capturing a BAR file, downloading and uploading the RPD, exporting a service instance, and importing a service instance. You'll also learn, through discussion, how and when each respective operation is used.
Just remember, a BAR technically has one or more of the following: a RPD, the Web Catalog, an Application Role security structure, and, potentially, other information about the Oracle BI environment that allows your instance of Oracle BI to be restored as fully as possible, providing the infrastructure of the Oracle BI system is otherwise in place.
Let's look at how this is accomplished.
Almost all the Oracle BI 12c LCM functionality is based on the interoperability of the WebLogic Server. The LCM functionality for exporting the Oracle BI instance artifacts to a BAR file requires use of the WLST:
- Open a command-prompt Terminal window, change the directory to the
BI Toolsdirectory, and execute the WLST command to start the WLST interface,<ORACLE_HOME>oracle_commoncommoninwlst.cmd. - Enter the following command, and be very careful with the use of double-quotes and single-quotes, as shown in the execution command:
exportServiceInstance( 'C:/OBI12cHome/user_projects/domains/bi' ,'ssi', 'C:/tmp/BAR/OBI12cBook/', 'C:/tmp/BAR/OBI12cBook/', 'ssi.OBI12cBook', 'OBI 12c Book BAR File', '3.0', true, 'Admin123')
- Press the Enter key to execute the preceding command.
- If the syntax was entered correctly, the script will run a series of tasks and this can take up to 10 minutes to complete, depending on how much metadata is configured in your instance.
The result of the preceding command execution will use WLST to call the function exportServiceInstance to reference the Oracle BI 12c domain home ('C:/OBI12cHome/user_projects/domains/bi), the serviceInstanceKey (ssi), work directory (C:/tmp/BAR/OBI12cBook/), and theexport directory (C:/tmp/BAR/OBI12cBook/), It will create an application name (ssi.OBI12Book), add a description (OBI 12c Book BAR file), give the BAR file a version (3.0), determine to export user folder information in this BAR file (true), and create a password to secure the RPD, which in turn allows the RPD to maintain its connection pool credentials (Admin123).
The results of your export should be that you have a BAR file now residing in the exportDir (export directory) path, in this example, C:/tmp/BAR/OBI12cBook/.
In some circumstances, you may want to use a different path value for exportDir and workDir, but for most purposes using the same directory serves the same purpose.
The following are the parameters for the exportServiceInstance function that was just called:
exportServiceInstance( domainHome, serviceInstanceKey, workDir, exportDir, applicationName=None, applicationDesc=None, applicationVersion=None, includeCatalogRuntimeInfo=false, includeCredentials=None )
The exportServiceInstance is the command that creates a BAR file. It always captures the core elements and artifacts described previously. It is on importing the service instance BAR snapshot that it can be determined which of the artifacts should be deployed into a target environment.
The following are the parameters for the exportServiceInstance:
|
Parameters |
Description |
|
|
Path to BI domain home. |
|
|
Key for the service instance. |
|
|
Work directory for the run. |
|
|
Directory where the BAR file is to be exported. |
|
|
Reserved for future use, but use as used in preceding code. |
|
|
Reserved for future use, but use as used in preceding code. |
|
|
Reserved for future use, but use as used in preceding code. |
|
|
Optional - If this flag is true, catalog runtime info (for example, user folders) is included in exports. Otherwise, catalog runtime info is skipped. The default value of this flag is false. |
|
|
Optional - This is the password to encrypt the exported metadata repository content. The default value for this field is None. If you do not specify this value, connection credentials are not exported; otherwise, connection credentials are exported. |
Now that you have exported your Oracle BI service instance, ssi, to a BAR file and you can see the physical file in the directory, it is time to import the BAR file back to Oracle BI. This can, of course, be done on the same server you conducted the exportServiceInstance exercise on, because ultimately you are just restoring a snapshot. Surely, the real-world example would be to conduct the steps for the importServiceInstance on a different server having an Oracle BI 12c installation, but for now the principle of the process is the equal. Let's import the BAR file and include all the artifacts:
- Use the existing command prompt Terminal window and change the directory to the
BI Toolsdirectory, or open a new one. - Execute the WLST command to start the WLST interface,
<ORACLE_HOME>oracle_commoncommoninwlst.cmd, if using a new window. - Enter the following command, and be very careful with the use of double-quotes and single-quotes, as shown in the following execution command:
importServiceInstance( 'C:/OBI12cHome/user_projects/ domains/bi','ssi', 'C:/tmp/BAR/OBI12cBook/ssi.OBI12cBook.bar', true, true, true, 'Admin123' )
- Press the Enter key to execute the preceding command.
If the syntax was entered correctly, the script will run a series of tasks and can take up to 10 minutes to complete depending on several factors such as size of the RPD, size of the Web Catalog, and so on.
The result of the preceding command execution will use WLST to call the function importServiceInstance to reference the Oracle BI 12c domain home (C:/OBI12cHome/user_projects/domains/bi), the serviceInstanceKey (ssi), the absolute file location on the server where the BAR file to import resides (C:/tmp/BAR/OBI12cBook/ssi.OBI12cBook.bar), decision to import the RPD (true), the decision to import the Web Catalog (true), the decision to import the application roles and policies (true), and the password used to decrypt the RPD metadata content, such as the connection pool credentials (Admin123).
Tip
Restarting the Oracle BI components and, technically, the entire Oracle BI system, is highly recommended to ensure that all artifacts are completely recognized by the Oracle BI system. Also, please understand that, with the import process, importServiceInstance will overwrite the existing artifacts on the target server based on the import option parameters (rpd, web catalog, security) marked as true. A best practice is to conduct an exportServiceInstance on the target server prior to conducting an importServiceInstance.
The importServiceInstance is the command that takes an existing BAR file and moves its contents, as directed, into the Oracle BI 12c ecosystem. By setting the optional parameters of the function, you effectively determine which of the artifacts to deploy into a target environment.
The following are the parameters for the importServiceInstance:
|
Parameters |
Description |
|
|
Path to BI domain home. |
|
|
Key for the service instance. |
|
|
Exported service instance BAR (absolute path). |
|
|
Optional - The value of this parameter can be true or false. The default value is true. This parameter supports selective import of metadata. If this flag is set to false, the command run does not import the repository metadata. |
|
|
Optional - The value of this parameter can be true or false. The default value is true. This parameter supports selective import of the catalog. If this flag is false, the command does not import the catalog. |
|
|
Optional - The value of this parameter can be true or false. The default value is true. This parameter supports selective import of the Jazn. If this flag is false, the command does not import the Jazn. |
|
|
Optional - This password is used to decrypt the imported RPD content. The default value for this field is Admin123. |
Tip
The last four parameters are optional. Entering those parameters with explicit values allows the execution of your code to be consistent in nature, and very visibly helps any readers of your code understand specifically what you are trying to accomplish. Only the first three arguments of the function are required, so in theory you only need to call importServiceInstance with the domain home, server instance name, and the BAR file location.
Because exportServiceInstance and importServiceInstance can be called via WLST, it also means that these items can be programmatically integrated into a scheduled process or into a custom-developed solution. For now, the basics are that capturing a BAR file is great for snapshot backups of the Oracle BI system and for migrating from one server to another.
The method of using importServiceInstance to move Oracle BI artifacts from one Oracle BI server instance to another is a great concept. There is the option with importServiceInstance to set only the option for importing the RPD and no other artifacts. This could be the preferred approach. However, one would still need to run the exportServiceInstance command, which technically will always take a snapshot of all artifacts even if you do not intend to reimport all of the artifacts. This command will look similar to the following code if attempting to import just the RPD from an exported service-instance BAR snapshot file:
importServiceInstance( 'C:/OBI12cHome/user_projects/domains/bi','ssi', 'C:/tmp/BAR/OBI12cBook/ssi.OBI12cBook.bar', importRpd=true, importWebCat=false, importJazn=false, includeCredentials='Admin123' )
Because the importing and exporting of the services is known to be time-consuming for immediate metadata repository development, there is an option to upload and download the RPD without using WLST.
An LCM CLI tool that resides in the BI Tools for moving the RPD is called data-model-cmd (data-model-cmd.cmd|sh). This command is multipurpose, but its primary use in this section is to move the RPD back and forth as simply as possible.
Tip
In the initial release of Oracle BI 12c, the BI Tool file, data-model-cmd, was introduced. It was changed in subsequent releases to a shorter file name, datamodel (that is, datamodel.sh or datamodel.cmd). This book will use the original file name. Please note they are interchangeable in the steps that follow.
To download the RPD from the Oracle BI server, follow these steps:
- Open a Terminal window command prompt and change the directory to
<ORACLE_HOME>user_projectsdomainsiitoolsin; for example,C:OracleOBIEE12cHomeuser_projectsdomainsiitoolsin. - Execute the following command:
data-model-cmd.cmd downloadrpd -O obi12cbook_dwnld.rpd -W Admin123 -U weblogic -P Admin123 -SI ssi
- Verify the file has been downloaded into the BI Tools directory; as the
-Oargument did not specify a different path, it will be downloaded into the same directory in which you currently reside. - The
downloadrpdoption has the following structure for arguments passed into it:downloadrpd -O RPDname [-W RPDpwd] -SI service_instance -U cred_username [-P cred_password] [-S hostname] [-N port_number] [-SSL] [-H]
When not editing the RPD in online mode and a developer needs to move the RPD from one Oracle BI server to another or even swap out their RPD in development, the straightforward approach is to upload the single RPD using the BI Tools, data-model-cmd, command using the uploadrpd option.
You can open the recently downloaded RPD in offline mode and make a change to one of the Subject Area names so that you will be able to determine if the rpd is actually uploaded to the server after running the command in the following steps. Save the RPD and upload it with the following instructions:
- If not already open and set to the
BI Toolsdirectory, open a Terminal window command prompt and change the directory to<ORACLE_HOME>user_projectsdomainsiitoolsin; for example,C:OracleOBIEE12cHomeuser_projectsdomainsiitoolsin. - Execute the following command:
data-model-cmd.cmd uploadrpd -I obi12cbook_dwnld.rpd -W Admin123 -U weblogic -P Admin123 -SI ssi
It will take a few minutes for the file to be uploaded by the command.
- Open the Oracle BI portal, /analytics/, web page, and click to begin creating a new analysis. Determine if the subject area is changed to the updated name, which will only exist in the RPD that you briefly modified.
The uploadrpd option has the following structure for arguments passed into it:
uploadrpd -I <RPDname> [-W <RPDpwd>] -SI <service_instance> -U <cred_username> [-P <cred_password>] [-S <hostname>] [-N <port_number>] [- SSL] [-H]
As a straightforward test, you can see how this process for uploading the RPD is relatively intuitive. You may have also noticed that the RPD changed without having to restart any of the Oracle BI system components. Oracle BI has a refresh that takes place by default every 10 minutes in the system, and it looks for changes to the RPD or changes based on BAR file updates in order to determine what it may need to refresh based on an administrator making changes to the system.
Tip
The BI Tools directory can be added to the PATH environment variable on your server so that you can easily call the commands, such as data-model-cmd.cmd|sh, from anywhere on your operating system, thus alleviating the need to specify an absolute path for the output argument, such as when you download the RPD.
Oracle BI 12c gives you several approaches to stop, start, or restart the Oracle BI System Components: via command-line interface (CLI), via JMX, and via the Enterprise Manager (EM) GUI. One approach is to use the EM as discussed in the preceding section. Another is to use the CLI executable that installs with Oracle BI. The last is a programmatic approach that is easily executable from Jython or Java coding.
In the Fusion Middleware Control (EM) console, restarting all components simultaneously using the Restart All button ensures that the Fusion Middleware Control will handle all serial communication with the WebLogic Management Framework (WMF) in order to correctly stop and start the system components in the necessary order.
However, there is a more advanced approach, which can be achieved by calling an executable on the server where the Oracle BI server is installed. This executable is located in the BI Tools path, <ORACLE_HOME>user_projectsdomainsiitoolsin; for example, C:OracleOBIEE12cHomeuser_projectsdomainsiitoolsin.
You can get a list of all components and their names by running the following status command from the command prompt within the preceding directory:
status.cmd
Please take note of all the component names, since they will be relevant in the stopping and starting of the system components.
To stop the Oracle BI system and all its system components, open a command prompt Terminal window. Then, execute the following command: stop.cmd, if on a Windows Operating System (OS), or stop.sh, if on a Linux or Unix OS.
The stop.cmd|sh command will stop all Oracle BI components in a specific order to prevent locking conflicts. It will also stop the node manager, the BI-managed Server, and the WebLogic Admin Server, to fully bring the Oracle BI system to a halt.
If you want to stop just a single component of the Oracle BI system, for example, if you need to restart the Presentation Services component after you've made a change to a configuration file, then use the -i switch in the stop command: stop.cmd -i obips1. In this case, only the component name that follows the -i will be acted upon for the action. If you need to stop multiple components, use the -i argument/switch and enter the names of the components, separated by a comma, but without spaces in between the comma or the names. For example, to stop the presentation services and BI Server services, use the following command:
stop.cmd -i obips1,obis1
Starting the Oracle BI system and all of its system components follows the exact same process as the stop command. Open a command prompt terminal window then execute the following command, start.cmd, if on a Windows Operating System, or, start.sh, if on a Linux or Unix OS.
The start.cmd|sh command will start all Oracle BI components in a specific order to prevent locking conflicts. It will also start the Node Manager, WebLogic Admin Server, the BI Managed Server and all of the system components to fully bring the Oracle BI system into operation.
If you need to start just a single component of the Oracle BI system, for example, if you the WebLogic Server is running and you need to need to restart the Presentation Services component after you've made a change to a configuration file, then use the -i switch in the start command: start.cmd -i obips1, after you execute the stop command. In this case, only the component name that follows the -i will be acted upon for the action. If you need to start multiple components, use the -i argument/switch and enter the names of the components, separated by a comma, but without spaces in between the comma or the names. For example, to start the presentation services and BI Server services use the following command:
start.cmd -i obis1,obips1
In the case of the start command, notice how, because the order of the components is specific, the syntax starts the Oracle BI Server Component first and the Presentation Services component second. This is a best-practice sequence for Oracle BI. It is illustrated here to show that, when specifying the start and stop processes, the sequence of components can make a difference.
As with most software, there can be bug fixes or new features that allow requested functionality in the current version of the software. These items would be considered patches and typically released in a patch download for your current software. A patch is normally associated with a particular version and involves updating from one minor version of the product to a newer minor version of the same product (for example, from version 12.2.1 to version 12.2.2). A patch set is a single patch that contains a collection of patches designed to be applied at the same time.
This would not necessarily be considered an upgrade to the current version of your software. Oracle releases immediate hotfix patches for Oracle BI software sporadically as customers with production-halting issues need them. Oracle releases quarterly patches that fix issues or apply general functionality improvements. And, once a year or so, they provide an upgrade of the solution to the next major or minor version of the software.
Typically, patches, when applied to Oracle BI, do not impact configuration files or non-design-time schema-based metadata such as scheduler, web catalog, and RPD files. Patches can be rolled back. One would roll back a patch, for example, if the new patch version actually causes issues when applied, even if it fixes the problem you anticipated the patch would resolve.
The patching process is beyond the scope of this book, but you can find more information about patching in the Oracle BI 12c documentation, at https://docs.oracle.com/middleware/1221/biee/BIESG/patching.htm.
This book will cover the basics of upgrading to Oracle BI 12c from a previous version of Oracle BI toward the end. However, there is the possibility that an upgrade from one version of the Oracle BI 12c system to another core release of Oracle BI 12c may be imminent. If so, the best instruction that can be provided is to follow the instructions included with any upgrade version of the software that may come along. As always, be sure to back up your artifacts and move all configuration files, artifacts, and customization files out of the ORACLE_HOME directory in which you installed Oracle BI 12c. Placing them outside that main folder should ensure that they will not be replaced or overwritten during the upgrade.
Oracle BI allows almost every crucial log file regarding the runtime of its artifacts to be visible from the Fusion Middleware Control EM console. This is very important when diagnosing issues, since you don't need to navigate to the file system in order to locate the respective service's log files. Oracle BI does something very clever with its log files, by using an Execution Context ID (ECID), which ties all log files together around one transaction or event. This way, a single error or failure will allow you to look across all components based on a particular event, using the ECID, to determine what caused an issue. Use the following steps to see how to get at some basic Oracle BI log information:
- Navigate to the Diagnostics > Log Messages sub-tab.
- Here you will see the most recent warnings and error messages across all system components and more.
- Scroll toward the bottom of this sub-tab section and notice the header View Log Messages.
- Click the Server Log link.
- This takes you to the Log Messages viewer specifically predicated on the Oracle BI Server logs. If no records are immediately shown, click the search icon above the table and change the Date Range fields to Most Recent 20 Days, or modify the day filter to a range that will have captured data since your Oracle BI installation, and click the Search button.
- Notice the results section is now populated. Scroll through the results looking for both errors, if any, and warnings, under the column heading Message Type. There should always be a few warnings, most of which can be ignored.
- Above the log messages table is a button drop-down labeled Export Messages to File. Click the drop-down button and select the option As Oracle Diagnostic Text (.txt).
- The log file contents from the search will process and a save file prompt will appear asking you to download or open the file.
- Download this file for later use when making a snapshot of issues or reporting issues to Oracle Support:
The Log Viewer is predicated on the target log file selection made, in this case, Server Log, as selected in Step 3. In order to view other log files within this area, click the Search button above the left side of the table to open the search window. Then expand the Selected Targets triangle area. Next, for example, scroll down and locate bi_server1, click the row, and click the respective Target Log Files icon to view the list of log files for bi_server1. Click on bi_server1.log toward the top of the table-list of log records, and then click on the View Log File button at the top of the table to view the log file in question.