Wednesday, 23 December 2015

Bursting Using OBIEE Agents Part 2: The Empire Bursts Back

Did you like the topical Star Wars reference? Have you seen the new film yet? Of course not, you've got bursting to do.

In my previous post Bursting Using OBIEE Agents Part1 we looked at how our dashboard was filtered by region using a session variable and we saw how an OBIEE agent can run the dashboard and save it to the file system. The format I chose was .PDF but there are other formats you can choose.

An analysis can be exported in all the above formats but a dashboard page is restricted to PDF, Excel and HTML.

In this post we shall:

  • Create a new analysis which will define which regions we want to burst.
  • Create a new agent which will save our regions as a list in a text file.
  • Use the SaSchinvoke command line utility to run the agents from the command line.

So, to recap here is my dashboard:

Notice the regions in our prompt....I want to burst my report out across my regions.

Bursting Definition

We shall now create a new analysis which will list out the regions to drive the bursting.

I don't care about the formatting, I just want my analysis to list the regions:

These are the droids regions we're looking for. Just filter your analysis to match your desired burst output.

We shall now create an agent which will export the region definition to a text file. The bursting agent has exactly the same configuration as the dashboard agent we created in the previous post with the following exceptions:

Delivery Content

Here we define our bursting definition analysis:

Agent Action

Here we define the file format of the exported bursting definition (plain text):

Run the agent and check that it is exporting our bursting definition to our Agent_Temp folder:

and review the contents:

Yep, those are the regions I want to burst out.


Saschinvoke is the Oracle BI Scheduler command line job invocation tool. On Windows it is called saschinvoke.exe and on *NIX it is saschinvoke. It enables you to schedule a job via the command line. It is typically used to launch jobs outside of the OBIEE scheduler using a 3rd party scheduler or batch routine. Saschinvoke isn't anything new and it's been covered in other blogs but it is key to our process so I'll explain how it works.

We shall use sachinvoke to launch our agent via a command script.

The utility can be found in OBIEE_HOME\bi\bifoundation\server\bin
so in my case it is located in: E:\Oracle\OBIEE\Oracle_Home\bi\bifoundation\server\bin.

Here is a link to the command in the Oracle Documentation.

The syntax for the command is:

SASchInvoke -u <Admin Name>  (-j <job id> | -i <iBot path>)  [-m <machine name>[:<port>]]  [(-r <replace parameter filename> | -a <append parameter filename>)]

We will only need the following parameters to launch our agent:
-u: User name
-i: iBot path (the path to our agent)
-m: machine:port

The syntax is as follows:

saschinvoke -u bi_admin -i "/shared/Blog/Agent Burst/Region_Burst_Agent" -m SERVERNAME:9511

You will be prompted for the password for your BI administrator user:

I've highlighted the machine:port parameter because this isn't needed in 11g. Oracle haven't taken into account the change in port numbers in 12c and the saschinvoke utility will fail without the machine:port reference because it still defaults to the old 9705 port.

So now we can use the command line to launch an agent which will write our dashboard and bursting definition to the file system. This is an important step because we can use the power of scripting to read our busting definition file and burst the dashboard for each region.

In part 3, the final part of the series, we will use batch scripting to launch our agents and burst out the dashboard for each region in the burst definition file.

Have a great Christmas break!


  1. Hi

    nice post! However, I'm missing Part 1. The link above is broken


    1. Hi Mike, I had put it in draft mode somehow. It should be back online now.

  2. Hi,
    I'm trying to run the command, but I get the following error:

    Execution Error: [nQSError: 12017] Unexpected socket read timeout: connection terminated by the network, e.g. by the firewall.
    [NQSError: 12008] Unable to connect to port 9502 on machine localhost.

    I tried to do as is suggested in this post:
    but it does not work the same.


    1. Hi Eleonora,
      I also got the same error as you when using OBIEE 12c because of the change in port number so I had to use the "-m SERVERNAME:9511" flag to make sure it was using the correct port to communicate with the scheduler. However, if you're on 11g then the port number should be the default 9502. Can you telnet to that port to verify that the scheduler is indeed running on port 9502?


    2. Hi Guillaume,
      I'm using 11g, the problem was the port ... the 9502 was not good, I put 9712 and now it works.
      Thanks so much!