Scripts to use Agents in OBIEE 12c: mass enabling and execution from a page

Few days ago I wrote about Agents in OBIEE 12c and how it was possible to enable them by script, automating that part of the process which was still manual.
This time I’m going to write about 2 examples of how I used my findings about Agents, providing the code as download so you can use it in just few seconds.

Two use cases as example

Today I’m going to cover two possible needs with Agents, one mainly for upgrades or code promotion between environments and the second to provide a functionality to the consumers of your OBIEE dashboards and analysis.

Execute an agent from a dashboard page / analysis

Mass enabling in one step of Agents

(Code is provided, feel free to look at it and adapt or use it as you want)

All the tests and analysis have been done on OBIEE 12.2.1.2.0.
The libraries are probably the same for the previous OBIEE 12c releases and will also work, with some little adjustments for OBIEE 11g (11.1.1.7, 11.1.1.9) as the main javascript libraries are the same.

Keep in mind jQuery wasn’t there in OBIEE 11g, so that’s the main change required.

Mass enabling of Agents in one step

In a running prod OBIEE you can easily have tens or hundreds of Agents: nothing bad with this, they provide functionalities for the consumers. But what happen when you upgrade your old PROD OBIEE 11g to OBIEE 12c? What happen to the Agents?

Well … the Agents end up on the new system but … all disabled ! Now have fun going through the full catalog, finding out which Agents must be enabled and enable them again one by one, by hand.
Not funny at all without forgetting the risk of missing some and have your consumers complaining your upgrade is actually a regression.

Stop fearing your next upgrade, you can enable all your Agents with few clicks from a single page.

Mass enabling Agents from an OBIEE dashboard page

As seen in previous post the OBIEE front-end catalog page uses a lot of javascript to interact with Agents, to enable them. So I put together some javascript code to use these OBIEE libraries to make my (and your) life easier.

In your OBIEE instance go in the Catalog and create a new empty folder (to avoid issues in case you have a dashboard with the same exact name of the one in the file already). Can be your personal folder or the shared folder, works in both places, the path doesn’t matter.

When the page open, it searches the Agents in the catalog and display a list of them (can take some seconds if you have lot of them)

A list of all the Agents found in the catalog.

Select the Agents you want to enable (or all of them using the “check all” link) and click the button. If you are sure confirm.

Select Agents from the list (or all with the “check all” link), click the “Enable selected agents” button and if you are sure confirm.

The javascript OBIEE libraries are doing the work now, the logs show you what’s happening in the background. Once done the list of Agents is reloaded with the new status (if enabled the checkbox isn’t active anymore).

While running the logs are added Agent by Agent and once done the list is reloaded (with the new status for Agents)

Done ! You can now enable lot of Agents at once.

If the page doesn’t work or take too long to load the list of Agents have a look at your browser console, it gives some output faster than the log box on screen.

Loading the list of Agents can take some time (10-15 seconds for 104 Agents). The console log give you an output of what’s going on while waiting.

How does it work?

The page is a normal dashboard page with “Text” elements containing some javascript and HTML.

Only some javascript and HTML

It uses the embedded jQuery in OBIEE 12c to manage everything: load the required files, actions on checkboxes and button, output to screen.
Completely uses the OBIEE javascript libraries, so it does exactly what the Catalog does, nothing else. There are just 2 methods which are overwritten as they can’t work outside the Catalog (to handle the result and update available actions on an Agent).

Feel free to take the code and change it as you want, you can easily add a disable action too. Something you will maybe want to do is to customize the search of Agents in the catalog by defining a specific path and pattern for names.

You can adjust the value of “path” and “mask” as you want, even add them on screen as text field for a more interactive experience.

All my tests and development have been done on a OBIEE 12.2.1.2.0 but the catalog file must be fine for other 12c versions too. For 11g you will have to adapt things as jQuery isn’t there by default even if the OBIEE javascript functions are probably (tested a bit) 95-100% identical.
I have enabled 102 Agents at once using this script: the page become unresponsive at the beginning when things are running but just leave it there, few minutes later all the Agents were enabled!

Important note: permissions & privileges

As this script does exactly what happen when you click one by one in the catalog the same limitations apply. If your users don’t have the required permissions on the catalog to access the Agents or to enable them this script will not bypass these limitations. It uses the privileges of your current session, so it’s advised to use it with an admin-like account.

Execute an Agent from a dashboard page or an analysis

Sometimes you want to allow your consumers to execute an Agent, run it immediately, from a dashboard page or an analysis. For example if you have somebody in charge of validation of some data/analysis before to send it out to a wider audience.

The approval can be done visually using a dashboard or an analysis, and then to send out the data/analysis you can use an Agent setup without schedule and containing the full list of people, so you find it in the Catalog and click on “Run” directly.

Wouldn’t it be better if you could have a button directly on the validation dashboard page?

In this code the path to the Agent is hardcoded, you can definitely change it or make it smarter (a generic event handler reading the path from an attribute of the button HTML tag). Can be executed by a link or anything else as long as it can be triggered in a way or another.

The execution window popup just like in Catalog.

A full example of the script in action.

Important note: permissions & privileges

As this script does exactly what happen when you click “Run” in the Catalog the same limitations apply. If your users don’t have the required permissions on the catalog to access the Agent or to run it, this script will not bypass these limitations. It uses the privileges of your current session.

Final word

As you saw in the above examples a lot is doable. OBIEE is a web application which means you can easily hack pieces and reuses its own libraries for your needs.

If you want to see the details of other actions available on Agents find the actionhandlerimpl.js file on your OBIEE instance (you will find the same file few times) and look inside. If you check the saw.catalogaction.IbotsActionHandler.prototype.handleAction function you see all the actions available in the Catalog for Agents and the same file has details on actions on other kind of objects.

Do not abuse it! If you end up recoding half of the UI you maybe chose the wrong tool for the job.

If it doesn’t work … that’s life: look at the code, analyse what happen, compare with the actual OBIEE native javascript, debug by adding logging and breakpoints.

Feel free to post a comment if you have issues using the code in 12.2.1.0.0 or 12.2.1.1.0, I can easily have a look at those versions, for 11g it’s a bit more difficult as I don’t have environments easily accessible.

28 Comments

Tal
on 19 March 2017 at 16:44

Hi,
Great post and solution. Thanks!
I am trying to use your code but it looks stuck (loading…)
Looking at the console provides the error : unexpected token = ( saw.dll line 228).
Also, looks like the functions do not load to the page.
Are you familier with that problem?

Hi,
Have a look at this thread on the OTN forum: https://community.oracle.com/thread/4023366
You find an example of the code to execute an agent from a button.
As said the main issue is 11g doesn’t have jQuery, a library making the handling of things a lot easier. But the OBIEE libraries are the same (or almost identical).

Perfectly worked like that quite a lot of times for me. So what you can do is look at the console of your browser and debug it from there, calling functions by hand to see if they are there and all the files loaded etc.

Hi Petr,
The script actually search in shared folders and the “my folder” of the connected user. If you look at the script you see the search uses the param “path: /” and not “path: /shared”.
The problem is that security is applied, and from the front-end of OBIEE you can’t navigate to other users folders, you have access only to your own “my folder”.
You can maybe use Catalog Manager (the client installed next to Admin tool), that one can search at a different level and also into /users folders as long as you have the right permissions.
But even by taking a list of objects from there the script will hang because when retrieving the agents details the security will kick in.

Hi Gianni,
I’m using OBIEE 12.2.1.2.0
I have similar requirement like to show and run agent from my dashboard.I have hard coded my agent path in the above script. But when click on run button on my dashboard throwing below error.
“Could not open Agent. If you are expecting to have access to this Agent, please contact your Administrator.”

Hi,
No config is needed but you must be allowed to run the agent. So standard permission model apply and any user wanting to click the button must have the same privileges if doing that in the catalog itself.

I can able to run the agent successfully from my catalog folder, no issues.
error on dashboard:
“Could not open Agent. If you are expecting to have access to this Agent, please contact your Administrator.”
So it seems an access issue.

dileep
on 2 November 2017 at 13:42

i had created a dashboard page and copy the scripts from manage agent to another dashboard page same i had taken text1, text2 text3,text4 but the result is showing same script which i copy and paste in dashboard could you please help me

Not sure I get exactly what your issue is: you copied the content of the page you got from the blog post into another page. But instead of having the working thing you see the code on screen? Did you check the checkbox “HTML”? Are you sure you copied the full content of the text blocks without losing (breaking) HTML tags around? Greetings to Oracle 😉

And the answer is what I said yesterday already: you have to check the “HTML” checkbox for the text block. In 12.2.1.3 Oracle added an extra security disabling HTML everywhere, so you have to enable it. That’s what Michael posted on the ODC thread.

It works perfectly in my system. I was able to execute an agent from the dashboard page. My question is how have you found this script ? Is this something present ? I can see ServerRequests.JS and AjaxRequest.js in my OBIEE environment. If we want to develop or modify scripts like this what is the starting point would you suggest ?

First: I would highly suggest you never edit a default file of OBIEE but create your own customization (so it has more chances to survive upgrades and patches). How I have found it? I looked for it. OBIEE is a web application, as such everything happening can be analysed using your browser and in that way you manage to find the right functions and how to call them. Just make sure to analyze enough how things are done by OBIEE so your customization will be aligned with it and aren’t going to introduce errors OBIEE itself would avoid.

This is works good and will be very handy when we roll out OBIEE 12c. It seems to be limited to locating/listing 300 Agents. I see the truncated=yes in the log messages. I don’t see a limit set in your code. Do you where this limit is set so that we can locate and list more than 300 Agents?
Thank-you!

Hi,
The limit of 300 is the limit you get in searching for objects in the catalog page.
I didn’t hit but there are 2 settings for the BI Presentation service which can maybe increase that limit:
– MaxSearchResultItemsToReturn
– ManageCatalogMaxItemsPerPage
They are both set by default to 300 and do not have a description giving more details on their real impact, but the names seems to match.
They need to be set in the OBIPS config file inside WebConfig/ServerInstance/UI.
Again: I didn’t test it, so can’t confirm it’s the thing you look for …

I would say you can’t … Replied on the ODC thread too. There are too many information required by an agent, so it’s kind of difficult to pass them as parameters. You can for sure create objects by scripts (webservices etc.) but it’s a different thing.