BI Application Archive (BAR) files are zipped-up copies of the RPD, Catalog and Security model metadata from a Service Instance. When deploying your BI application from one server to another you can now use these BAR files to transfer your metadata rather than transferring the RPD, catalog and security model separately. It’s also a simple method of taking point in time backups of your application.
There is no web based tool for administering BAR files, it’s all done at command line through the Weblogic Scripting Tool (WLST) which is invoked with the following command:
<obiee_home>/oracle_common/common/bin/wlst.sh
(or wlst.cmd for windows)
A quick aside…to exit from the WLST command line use the exit() command – you must include the two brackets, ‘exit’ by itself doesn’t work!
Also note that all WLST commands are case sensitive and do include both upper and lower case letters, so the listBIServiceInstances command below cannot be spelt listbiserviceinstances.
Before we look at the commands for exporting & importing BAR files, there are some parameters you will need to know before we start.
Domain Home: This is the directory of the domain for your BI Install, this will usually be <obiee_home>/user_projects/domains/bi
Service Instance Key: The instance key of the BI Service you are interacting with. A Domain home can contain many instances and the name of the instance key you create during the installation. The default name is ‘ssi’, bit obviously could be different.
To view all the service instances use the WLST command listBIServiceInstances(domainHome):
listBIServiceInstances('/u01/app/obiee/user_projects/domains/bi')
So here I have one ServiceInstance and its key is ssi.
You also need a working directory and an export directory. The working directory is where the export command will temporarily store files during its processing. The export directory is where the BAR files will be stored.
I’ve created two new directories for this: /u01/workDir and /u01/exportDir. Anywhere will do, as long as the OS user you are running the scripts under has read/write access.
So to create a BAR file from your service instance use the exportServiceInstance command. This takes the following parameters:
Domain Home: e.g. <obiee_home>/user_projects/domains/bi
Service Instance Key: e.g. ssi
The working directory: e.g. /u01/workDir
The export directory: e.g. /u01/exportDir
There are then three unused parameters, supposedly reserved for future changes to the export command.
Include Catalog Runtime Info: The Runtime info is user-based information, such as the users own folders. By default this parameter is set to ‘false’. Use ‘true’ if you do want user info. This parameter is optional.
Include Credentials: This is a password field to encrypt the database connection credentials in the RPD. This field is optional and if not included the connection credentials are not exported.
With three unused parameters and the final two being option you can run the exportServiceInstance command with just the first four parameters:
exportServiceInstance('/u01/app/obiee/user_projects/domains/bi','ssi','/u01/workDir','/u01/exportDir')
If you do want to specify the last two parameters then use quotes to pass over the three unused parameters, e.g.:
exportServiceInstance('/u01/app/obiee/user_projects/domains/bi','ssi','/u01/workDir','/u01/exportDir','','','',true,'Password1')
A log file is created of the export, under <obiee_home> /user_projects/domains/bi/bilogs/service_instances/ssi/metadata/ but it just contains the same text displayed on the screen during the export process.
The export file will be called serviceInstanceKey.bar, e.g. ssi.bar in my case, in the export directory.
At this point I’d usually rename it to something more meaningful to indicate what’s in the export file and the date taken.
Running the export without the user runtime info and credentials parameters does indeed produce a smaller file (only slightly in my case, I don’t have much in my test environment!)
exportServiceInstance('/u01/app/obiee/user_projects/domains/bi','ssi','/u01/workDir','/u01/exportDir')
Now we can look at importing an Application Archive file. You can import into the same serviceInstance that it was exported from (effectively restoring the metadata), or into a different serviceInstance (on the same server or another).
In the examples below I’m importing into a new OBIEE 12c installation on a different server, although the serviceInstance has the same key of ‘ssi’.
Before importing the files they need to be FTP’d across to the server where they are being imported into. The import command doesn’t need a working directory like the export command and to import you do specify the name of the file (with its full path), it doesn’t have to be named after the serviceInstance Key.
When importing a BAR file you can choose whether to import all three components (RPD, catalog, security model), or just selected elements. To import a BAR file you need to use the importServiceInstance command. This takes the following parameters:
Domain Home: e.g. <obiee_home>/user_projects/domains/bi
Service Instance Key: Of the service you are importing into, which may be different to the one it was exported from.
BAR file to import: The full path and filename of the BAR file
Import the RPD?: Should the RPD be imported from the BAR file. The default value is true, change to false if not wanted.
Import the WebCat?: Should the Web Catalog be imported from the BAR file. The default value is true, change to false if not wanted.
Import the Security model: Should the security model be imported from the BAR file. The default value is true, change to false if not wanted.
Include Credentials: This is the password used to encrypt the database connection credentials in the RPD. If not provided the connection credentials will not be imported.
Now according to the System Administrators guide for OBIEE 12c, there are two more parameters, one for to determine if user run-time info should be imported and another asking for the include credentials password again. These are not required and will produce an error if used. The importServiceInstance command can only have a maximum of seven parameters.
Only the first three parameters are compulsory, the others are all optional, however you must include all parameters up to the last one you specify (you can’t for instance include the credentials password without the three content import options before it).
So an example of the shortest form of the command would be:
importServiceInstance('/u01/app/obiee/user_projects/domains/bi','ssi','/u01/importDir/ssi.bar')
This would import the RPD, catalog and security model, but not the user runtime info. The connection credentials would not be imported(if they are even in the file)
And the longest form:
importServiceInstance('/u01/app/obiee/user_projects/domains/bi','ssi','/u01/importDir/ssi.bar',true,true,true,'Password1')
In this case everything is imported. In most cases when you’re using a frequently used script for deploying content, say from development to production, the following command is probably best:
importServiceInstance('/u01/app/obiee/user_projects/domains/bi','ssi','/u01/importDir/ssi.bar',true,true,false,'Password1')
This imports the RPD (with connection credentials) and the catalog but not the security model or the user run-time information.
So an example of running it produces the following:
The import has completed and appears to have been successful…and indeed it has, but initially things look a little odd…my user (paulc in the screenshots below) can see the new dashboard that was in the export and the dashboard has data, so the RPD must have loaded too (with the connection credentials):
Also the catalog is showing the run-time user info (i.e. the reports I had saved into my folder) and I can see the Revenue Reports shared folder.
But…my user paulc is an administrator and had full admin rights…but no I don’t have the Administration option in the menu bar and I can’t create new Analyses, filters or prompts!
Even weirder, if I load the Admin tool and connect on-line only the Sample App metadata is there (which I deleted), there’s no sign of my revenue data metadata even though the revenue reports are working on the dashboard!
Clearly something hasn’t been completed. The importServiceInstance seems to import things ok, but it doesn’t perform a restart of the OBIEE services and this is clearly what’s needed.
So after performing a full restart using the normal stop & start scripts I now have my admin permissions back and the on-line RPD does show my metadata:
So the answer is always restart OBIEE after performing a BAR import. You needed to when deploying an RPD in 11g via the enterprise manager, so it’s no worse than before.
The real improvement is the ease with which you can now include catalog and user run-time info and that it can now be scripted rather than manually working through the enterprise manager screens – a big tick in the box from me!
Enjoy!
No comments:
Post a Comment