This chapter describes how to manage Oracle Business Intelligence metadata in BI Application Archive (BAR) files, and how to work with Service Instances.
This chapter includes the following sections:
This topic contains the following sections:
An Oracle Business Intelligence application archive (BAR) file is a compressed archive file that contains a cohesive set of BI metadata artifacts (data model, content model, and authorization model). A BAR file can be imported into a BI Service Instance. You can backup a BI Service Instance into a BAR file, and subsequently restore it either to the existing service instance running in the BI domain, or into a different service instance running on a different BI installation.
A BAR file contains the following BI application module artifacts:
Data model metadata for the Oracle BI Server. This metadata is xml-based but functionally equivalent to a .RPD file.
Presentation Services catalog metadata for a service instance.
Security policy metadata containing application role and application role memberships plus permission and permission set grants for a service instance.
A manifest file declaring the dependencies for the BAR file.
Oracle provides a number of predefined BAR files, containing BI metadata to use with a service instance.
You can choose one of the following BAR files during installation:
Empty BAR - oracle.bi.application.empty.bar
The empty BAR file enables you to have complete control over metadata and security policy, or you may simply have an existing BAR from another system that you might want to import.
ORACLE_HOME/bi/bifoundation/admin/provisioning/oracle.bi.application.empty.bar
The Empty BAR file contains only enough permissions for the administrator user to login and administer the system.
Table 9-1 shows the application role and corresponding permission sets that come with the Empty BAR file.
SampleAppLite BAR - SampleAppLite.bar
You can select SampleAppLite at install time (see Oracle Fusion Middleware Installation Guide for Oracle Business Intelligence).
The SampleAppLite BAR enables you to start using BI Analytics straight away, enabling you to demonstrate the functionality of the product.
The SampleAppLite BAR file contains a file based data source with 2 subject areas, a collection of reports, and application roles for read, write, and administration tasks.
ORACLE_HOME/bi/bifoundation/samples/sampleapplite/SampleAppLite.bar
Table 9-2 shows the application roles and corresponding permission sets that come with the SampleAppLite BAR file.
Table 9-2 Application Roles And Permission Sets in SampleAppLite BAR
| Application Role | Permission Set |
|---|---|
|
BIServiceAdministrator |
obisch.administrator essbase.administrator obips.administrator cds.administrator bip.administrator obis.administrator |
|
BIConsumer |
bip.consumer |
|
BIContentAuthor |
va.author obisch.author bip.author |
For more information, see Section 1.6, "Working with the Sample Application".
Starter BAR
You use the starter BAR when you want to build metadata from the beginning, but need a typical security policy to be in place.
The starter BAR is essentially empty except for containing the same security policy as the Sample application BAR.
For example, if you want to create a service instance for Visual Analyzer where users will import their own data from scratch, by importing the starter BAR into your service instance it means that you only have to provision users with the starter application roles and they can immediately login and start using the product.
When you import a BAR file into a service instance, the service instance will use the data model, content and security policy imported from the BAR file.
The import process does the following:
Takes the content, model and security policy defined by the BAR, and deploys it to a Service Instance.
Overwrites any existing content, model, security policy already established in the Service Instance.
A service instance contains all of the Oracle Business Intelligence metadata (that is, repository data, presentation catalog, security policy), and includes the customizations that you make to the metadata. You manage a service instance in an BI domain using WebLogic Scripting Tool (WLST) commands described in Table 9-3.
For information about using WLST, see Section 8.3.3, "Using the WebLogic Scripting Tool (WLST)").
Table 9-3 Oracle Business Intelligence Service Instance Commands
| Command | Description |
|---|---|
|
This command lists all Service Instance keys in the BI domain. |
|
|
This command gets service instance details for a given service instance key. |
|
|
This command scales-out the Service Instance(s) onto the new computer, ensuring that the service instance is available on the specified computer within the BI domain. This command is only used in advanced cases. |
|
|
This command exports a service instance to a given export directory in the form of BAR file. |
|
|
This command imports an already exported bar (service instance) as a customization to a given environment. |
|
|
This command refreshes certain aspects of a service instance serviceKeythat are inherited from the BI domain. For example, if a new module or product is added to the BI domain, the permission sets for that module or product will only be made available to the service instance when the service instance is refreshed. |
|
|
This command refreshes all the service instances of the domain. |
|
|
This command resets the given service instance to empty state equivalent to importing the empty BAR file. |
Table 9-4 Parameters Used With 'Managing Domain Service Instances' Commands
| Parameters | Description |
|---|---|
|
domainHome |
Path to BI domain home. /oraclehome/user_projects/domains/bi |
|
serviceInstanceKey |
Key for the service instance to be associated with, or scaled out to. For example: mycompany.facility |
|
machine |
Name of the computer to which you are scaling out. For example: machine=mycompany.example.com |
|
port |
The port number to use on the scaled out computer. For example: port=9768 |
|
monitorPort |
Name of the monitor port to use on the scaled out computer. For example: portMonitor=9502 |
Assumptions for all WLST commands against BI Service Instances and BAR files:
You must have file system (offline) permissions.
You run the WLST commands offline.
You must start your system after making changes to service instances through WLST.
This task enables you to list all Service Instances.
To list all service instances:
Start the WLST command line scripting tool.
For information, see Section 8.3.3, "Using the WebLogic Scripting Tool (WLST)".
Enter command, for example:
listBIServiceInstances(domainHome)
Where domainHome is the path to BI domain home.
For example:
listBIServiceInstances('/oraclehome/user_projects/domains/bi')
The command returns a list of Service Instance Keys
For more information, see Section 9.2.2, "getBIServiceInstance"
This command displays service instance details. Information includes but is not limited to:
Metadata configuration: application association and customizations.
Component details.
Description.
To display service instance details:
Enter the following command to fetch the specified Service Instance details:
getBIServiceInstance(domainHome, serviceInstanceKey)
For example:.
getBIServiceInstance('/oraclehome/user_projects/domains/bi', 'mycompany.facility')
The command returns a service instance object containing details including, but not limited to:
Service instance key.
Description.
List of components.
List of application modules.
This command scales-out the service instance(s) onto a new computer to make the service instance available in the domain. Use this command if a service instance is created after availability is increased. For more information, see "Managing Availability in Oracle Business Intelligence (Horizontally Scaling)".
scaleOutBIServiceInstance(domainHome, serviceInstanceKey, machine, port=None, portMonitor=None)
This command returns a Service Instance object containing details.
Assumptions:
All ports will be allocated from the default BI port range, unless you provide them.
Cluster Controller, Scheduler and BI Server mastership is unchanged.
You must start new component(s), noting that Administration Server and Node Managers must be started first if offline, see Section 2.3.2, "Starting Oracle Business Intelligence Component Processes in a Domain".
Table 9-5 lists the parameters for this command.
Table 9-5 Parameters For Scaling Out a Service Instance For High Availability
| Parameters | Description |
|---|---|
|
domainHome |
Path to BI domain home. |
|
serviceInstanceKey |
Key for the service instance to be scaled out. |
|
machine |
Name of the computer to which you are scaling out the service instance. |
For example,
scaleOutBIServiceInstance('/oraclehome/user_projects/domains/bi','mycompany.facility', 'example.com')
Post Conditions:
New component(s) are created.
New ports(s) are allocated.
New Service Instance is registered.
This command exports a service instance to a specified export directory as a BAR file. You can then import the BAR file into another environment or within the same environment. Details of these optional parameters are given in Table 9-6.
exportServiceInstance(domainHome serviceInstanceKey workDir, exportDir, applicationModuleName, applicationModuleDesc, applicationModuleVersion, includeCatalogRuntimeInfo, includeCredentials)
Table 9-6 lists the parameters for this command.
Table 9-6 Parameters For Exporting A Service Instance
| Parameters | Description |
|---|---|
|
domainHome |
Path to BI domain home. |
|
serviceInstanceKey |
Key for the service instance. |
|
workDir |
Work directory for the run. |
|
exportDir |
Directory where BAR file is to be exported |
|
applicationModuleName |
Reserved for future use. |
|
applicationModuleDesc |
Reserved for future use. |
|
applicationModuleVersion |
Reserved for future use. |
|
includeCatalogRuntimeInfo |
Optional - If this flag is true, catalog runtime info (for example, user folder) is included in export. Otherwise catalog runtime info is skipped. The default value of this flag is false. |
|
includeCredentials |
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. |
For example,
exportServiceInstance( '/oraclehome/user_projects/domains/bi','mycompany.facility', '/workDir', '/scratch/exportDir')
exportServiceInstance('/oraclehome/user_projects/domains/bi/','mycompany.dev', '/scratch/workDir', '/scratch/exportDir', 'mycompany.dev.test' , 'mycompany dev test', '11.1.1.0')
exportServiceInstance('/oraclehome/user_projects/domains/bi/','mycompany.dev', '/scratch/workDir', '/scratch/exportDir', 'mycompany.dev.test' , 'mycompany dev test', '11.1.1.0', true, 'Test123')
exportServiceInstance('oraclehome/user_projects/domains/bi/','mycompany.dev', '/scratch/workDir', '/scratch/exportDir', 'mycompany.dev.test' , 'mycompany dev test')
exportServiceInstance('/oraclehome/user_projects/domains/bi/','mycompanyexample.dev', '/scratch/workDir', '/scratch/exportDir', None , 'mycompany dev test')
This command imports the BI metadata from a specified BAR file into a target service instance.
importServiceInstance(domainHome, serviceInstanceKey, barLocation, importRpd, importWebcat, importJazn, includeCredentials, includeCatalogRuntimeInfo, includeCredentials)
Table 9-7 lists the parameters for this command.
Table 9-7 Parameters For Importing A Service Instance
| Parameters | Description |
|---|---|
|
domainHome |
Path to BI domain home. |
|
serviceInstanceKey |
Key for the service instance. |
|
barLocation |
Exported service instance bar absolute path. |
|
importRpd |
Optional - The value of this parameter can be true or false. The default value is 'true'. This parameter support selective import of metadata. If this flag is set to be 'false', the command run does not import the repository metadata. |
|
importWebcat |
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. |
|
importJazn |
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. |
|
includeCredentials |
Optional - This password is used to decrypt the imported rpd content. Default value for this field is "Admin123". |
|
includeCatalogRuntimeInfo |
Optional - If this flag is true the catalog runtime info (user folder etc.) is included in export. Otherwise catalog runtime info is skipped. The default value of this flag is false. |
|
includeCredentials |
Optional - This password encrypts the exported metadata repository content. The default value is None. If this parameter is not specified connection credentials are not exported. Otherwise, connection credentials are exported. |
For example,
importServiceInstance( '/scratch/mydir/oraclehome/user_projects/domains/bi','mycompany.facility', '/scratch/exportDir/mycompany.finance.bar')
importServiceInstance('/scratch/mydir/oraclehome/user_projects/domains/bi', 'demosvc1', '/scratch/mydir/oraclehome/bi/bifoundation/samples/sampleapplite/test/SampleAppLite1.bar', true, false, false, 'Test123')
importServiceInstance('/scratch/mydir/oraclehome/user_projects/domains/bi', 'demosvc1', '/scratch/mydir/orahome/bi/bifoundation/samples/sampleapplite/test/SampleAppLite1.bar', importRPD=true,includeCredentials='Test123')
This command refreshes certain aspects of a service instance that are inherited from the BI domain. For example, if a new module or product is added to the BI domain, the permission sets for that module or product will only be made available to the service instance when the service instance is refreshed.
refreshServiceInstance(domainHome, serviceKey)
Table 9-8 lists the parameters for this command.
Table 9-8 Parameters For Refreshing A Service Instance
| Parameters | Description |
|---|---|
|
domainHome |
Path to BI domain home. |
|
serviceKey |
Key for the service instance. It is a unique identifier for the service instance. |
For example,
refreshServiceInstance('/oraclehome/user_projects/domains/bi', 'mycompany.finance')
This command refreshes all the service instances of the BI domain.
refreshDomainServiceInstances(domainHome)
Table 9-9 lists the parameters for this command.
Table 9-9 Parameter For Refreshing All Service Instances
| Parameters | Description |
|---|---|
|
domainHome |
Path to BI domain home. |
For example,
refreshDomainServiceInstances('/oraclehome/user_projects/domains/bi')
This command removes all the customizations in a given service instance (similar to an empty BAR state).
resetServiceInstance(domainHome, serviceKey)
Table 9-10 lists the parameters for this command.
Table 9-10 Parameters For Resetting A Service Instance
| Parameters | Description |
|---|---|
|
domainHome |
Path to the BI domain home. For example, /oraclehome/user_projects/domains/bi. |
|
serviceKey |
Key for the service instance. It is a unique identifier for a service instance. For example, 'ssi'. |
Example - To use the resetServiceInstance command to remove customizations:
Configure Oracle Business Intelligence with an empty service instance (the same as using an empty BAR file).
Note: The empty BAR file is here:
$BI_PRODUCT_HOME/bi/bifoundation/admin/provisioning/oracle.bi.application.empty.bar
Deploy SampleAppLite to the BI domain and associate it with the service instance.
Make some customizations on top of the base BAR.
Use the resetServiceInstance command.
For example,
resetServiceInstance('/oraclehome/user_projects/domains/bi', 'ssi')
This removes the customizations created in step 3 and returns the service instance to the state of step 2.