Managing Service Instances

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 the table below.

See Using the WebLogic Scripting Tool (WLST).

Command	Description
listBIServiceInstances	This command lists all Service Instance keys in the BI domain.
getBIServiceInstance	This command gets service instance details for a given service instance key.
scaleOutBIServiceInstance	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.
exportServiceInstance	This command exports a service instance to a given export directory in the form of BAR file.
importServiceInstance	This command imports an already exported bar (service instance) as a customization to a given environment.
refreshServiceInstance	This command refreshes certain aspects of a service instance serviceKey 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.
refreshDomainServiceInstances	This command refreshes all the service instances of the domain.
resetServiceInstance	This command resets the given service instance to empty state equivalent to importing the empty BAR file.

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.

listBIServiceInstances

This command enables you to list all Service Instances.

Start the WLST command line scripting tool.

See 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

See getBIServiceInstance.

getBIServiceInstance

This command displays service instance details.

Information includes but is not limited to:

Metadata configuration: application association and customizations.
Component details.
Description.

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.

scaleOutBIServiceInstance

This command scales-out the service instances 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. 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 components, noting that Administration Server and Node Managers must be started first if offline. See Starting Oracle Business Intelligence Component Processes in a Domain.

The following table lists the parameters for this command.

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.

exportServiceInstance

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 the table below.

exportServiceInstance(domainHome serviceInstanceKey workDir, exportDir, applicationModuleName, applicationModuleDesc, applicationModuleVersion, includeCatalogRuntimeInfo, includeCredentials)

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')

importServiceInstance

This command imports the BI metadata from a specified BAR file into a target service instance.

importServiceInstance(domainHome, serviceInstanceKey, barLocation, importRpd, importWebcat, importJazn, includeCredentials)

The table below lists the parameters for this command.

Parameters	Description
domainHome	Path to BI domain home.
serviceInstanceKey	Key for the service instance.
barLocation	Imported 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.

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')

Note:

When you import a 12.2.1.2.0 BAR File into an earlier Oracle BI EE release like 12.2.1.1.0 and 12.2.1.0.0, and the BAR file contains dataset metadata (for example an Excel spreadsheet) which is not supported before 12.2.1.2.0, the dataset metadata is not imported and the metadata that is not imported, is also not logged. The behavior is outlined as follows:

When a higher version BAR containing dataset metadata (for example an Excel spreadsheet sales.xls) is imported into an earlier Oracle BI EE release that does not support dataset metadata, the import process silently skips the dataset metadata content that is present in the later version (release 12.2.1.2.0 and higher) imported BAR.
The service instance log provides the information of metadata that will be imported. But it does not provide the information of metadata that will be ignored as part of import operation

refreshServiceInstance

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)

The following table lists the parameters for this command.

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')

refreshDomainServiceInstances

This command refreshes all the service instances of the BI domain.

refreshDomainServiceInstances(domainHome)

The following table lists the parameters for this command.

Parameters	Description
domainHome	Path to BI domain home.

For example,

refreshDomainServiceInstances('/oraclehome/user_projects/domains/bi')

resetServiceInstance

This command removes all the customizations in a given service instance (similar to an empty BAR state).

resetServiceInstance(domainHome, serviceKey)

The following table lists the parameters for this command.

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

This example removes customizations using the resetServiceInstance command.

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.