Agents in OBIEE 12c and 11g, known as iBots back in OBIEE 10g, are a component of the BI platform providing few interesting things like pushing data to users instead of requiring users to connect and get it themselves, have alerts based on data to inform users about something and few more. They are one of the many kind of elements you find in the OBIEE catalog.
Being part of the catalog means they are one of the elements you have to manage when upgrading to a different version of OBIEE or, more frequently, when promoting code/features between environments: from DEV to TEST and finally to PROD for example.

What are Agents?

Agents enable you to automate your business processes.
You can use agents to provide event-driven alerting, scheduled content publishing, and conditional event-driven action execution.
(FMW User’s Guide for OBIEE 12c)

Till here nothing special: archive your catalog (or branch of catalog) from system A and unarchive on system B: done!
Well … not really …
The objects end up on system B, your Agents will be there, sure, but they will always be disabled, so inactive, even if they were enabled and running on the source system.

This is currently an issue as you have to remember which Agents must be enabled and do it by hand on the target system, making automated code deployment only partial waiting for somebody to enable Agents again.

And what about migrations? For example, moving from OBIEE 11g to OBIEE 12c? You maybe migrate a catalog with tens or hundreds of Agents all over the catalog which must be enabled again … by hand! Not what we can call a nice and interesting activity and not the safest way to do a migration.

No need to enable them by hand anymore !

I’m glad to tell you that you don’t have to do it by hand anymore and the process enabling Agents can perfectly be scripted!

How? That’s for the bottom of the post, first let’s have a look at what an Agent is in OBIEE, what pieces of information are stored where.

Creating an Agent

To create an Agent is a really simple activity: in the “New” menu of the OBIEE web interface Agents are under the Actionable Intelligence label (by the way, if you don’t have a Foundation license but by component, make sure you are allowed to use deliveries). In the “Schedule” step is where the details about when the Agent must be executed are defined, if you uncheck the “Enabled” checkbox the Agent will not be executed, even if I define a schedule, for example every 10 minutes all the time, the Agent will not be run at all. That’s the status all the Agents are when migrated or promoted to a different environment.

In the “New” menu select “Agent”

Do not enable it directly, first define all the settings.

Save the Agent, it is still not enabled at this point.

Where the Agent is stored?

There are two places where information about Agents are stored.
The main place is the catalog itself, as any other object, the XML describing the Agent is created in a file (with a corresponding .atr file).

This is the content of that file for a sample Agent I just created:

Another place where you find information about the Agents is the database, the BIPLATFORM schema created by the RCU when OBIEE has been configured.
There are few tables for Agents there, the main one is S_NQ_JOB which is the one defining the ID assigned to each Agent (the JOB_ID column) registered by the Scheduler (one of the components of OBIEE).

Entries for the Agents in the S_NQ_JOB table

If you look well, between the XML and the database table there is a link: the XML contains the ID which has been assigned to the Agent in the S_NQ_JOB table. The “driver” isn’t the XML but the database as we will see later in case of conflicting IDs.

The jobID attribute of the saw:ibot node contains the ID assigned in the database

How to enable an Agent?

Once your Agent exists you can of course edit it again and check the “Enabled” checkbox and save, but there is a simpler way. In the catalog clicking on the “More” link just underneath the Agent itself a list of actions is displayed and if the Agent isn’t already enabled the last option will be “Enable Schedule” (if the Agent is already enabled you will have the link to disable it).

The “enable” link is available in the catalog

How to enable Agents by a script in an automated way?

As I’m not aware of a simple webservice to enable the Agents (didn’t search for it in detail as few other people who needed it said it wasn’t there, so I trusted them) the solution must be behind the “Enable Schedule” link in the catalog.

All I have to do is to find that piece of code, easy …

Let me introduce you saw.catalogaction.IbotsActionHandler.prototype.enableIBotSchedule, the enableIBotSchedule method of the saw.catalogaction.IbotsActionHandler javascript object. That’s a custom object Oracle developed (there are many many others, a lot more) to manage all the interactions with the catalog in the webpage.

This piece of code is, all in all, quite readable even without knowing what does call it, what’s the context and what there is around. A single parameter, by the code I would guess it can be an object or a reference to the Agent, actually the ” l ” parameter is just the path of the Agent, so something like /shared/Example agents/Test Agent 01 for the example Agent I created above.

If you look in your browser’s Developer tools extension what happen when you click the enable link the javascript code makes even more sense.

When clicking on “Enable Schedule” there are 2 ajax calls.

Looking at the URLs it’s easy to match these 2 ajax calls with the javascript code: row 5 and 42 in the above snippet.

To make it easier to understand the rest of the javascript function, this is the result of the first call to saw.dll?RetrieveIBotInfo :

The key element is at row 2: <SchedulerRegistered>1</SchedulerRegistered>
It means the Agent is already registered in the Scheduler, the database entries are there and are fine !
If the Agent wasn’t found in the database (in case of a migration for example) or there would be an issue the value would have been 0.

Based on this XML the rest of the javascript code make sense too as it’s a lot of XML manipulations: if the Agent is already registered in the Scheduler and there is a date for the schedule the code remove the disabled=”true” attribute from the saw:schedule node and then save the new Agent code.

This is actually the same as if you open the Agent to edit it, check the “Enabled” checkbox and finally save the Agent, same thing, same process, same logic.

You now have all the pieces to script and automate these steps if you want, simple standard HTTP calls sending and receiving pieces of XML (almost XML in reality, there is a kind of prefix you have to remove to make it really XML).

You can use the scripting language of your choice and after simulating a login to have a session ID with the required privileges you can execute the same logic and same HTTP calls.

Job ID collision: how is that managed?

Based on what I just wrote you can imagine you could easily have a Job ID collision when promoting code between environments.

For example, if you have 5 Agents in total in DEV and PROD and you add a new one while developing in DEV. This new Agent will have the ID = 6.
In the meantime in PROD a new Agent is created for a special need only in PROD (if you allow that or not it’s a different thing, processes are all different). In PROD the ID = 6 is assigned to this new Agent.

What happen when you promote your development till PROD? You will have 2 Agents with ID = 6: one will be the one promoted by your development release, the other the one created only in PROD.

Job ID collision? Panic! 2 Agents but same Job ID

No need to panic, OBIEE is smart!

The collision is detected, the system will see there is a second Agent with the Job ID = 6 but the path is different when compared with the one stored in the S_NQ_JOB_PARAM database table. It will discard the JobID = 6 and will create a new one when saving and enabling the Agent.

The metadata of the Agent mismatch with the attributes saved in the database

You can test this case by simply copy/paste an existing Agent to a new path in the catalog or with a different name.

To resume

Agents are stored in the catalog but also in the database once they are registered with the Scheduler (enabled or disabled doesn’t matter at this point).
This means that when deploying Agents in a new environment you do not have to care about the content of the S_NQ_JOB and S_NQ_JOB_PARAM database tables, OBIEE will manage that for you. It’s actually better to not write inside these tables by hand trying to migrate content.

Just to be sure you didn’t miss it…

Don’t copy the content of S_NQ_JOB and S_NQ_JOB_PARAM around between environments during code promotion or upgrades. Let OBIEE create these entries.
If needed, you can then copy the content of the log table, but first map the old Job IDs to the new ones.

No need to worry about conflicting Job ID in case you allow your users to create Agents directly in PROD and so ending up with the same ID of the Agents you deploy when releasing new features. OBIEE will detect the conflict thanks to the database and reassign IDs as needed.

Finally, and most important: you can script and automate the steps to enable Agents by replicating the simple javascript function logic: retrieve the Agent XML details, manipulate them a bit to remove the “disabled” attribute and save the Agent again.

Do you want a super simple way to do this in one step from OBIEE itself? Stay tuned, in few days I will post a Dashboard page containing all the code to select all the Agents you want to enable at once and with a single click they will be enabled, using the OBIEE javascript libraries (so it’s like if you will do it by hand in the catalog one by one). All you have to do is to unarchive it somewhere in your catalog.
Do you need to be able to execute an agent by clicking a button or link in an analysis or dashboard? Same as above: stay tuned and in few days a sample code will be posted.

Share This