Recently I had a chance to work a fair bit with Cognos Analytics Rest API to automate security and thought I’d share some learnings and lessons along the way.
In the initial stage of the project when we were debating whether to use REST API or SDK for automation and I was pushing for REST API as I wanted to use Python, one of the team members mentioned that “Python has way too many libraries”, so I had to create another one by publishing the Python wrappers for Cognos Analytics calls I used :)
So if you’re after being able to run code like this in Python:
ca_service = CognosAnalyticsService(ca_url='https://your_cognos_dispatcher:9300') # Login ca_service.login(namespace='namespace',user='user',password='pwd') # get list of content items from team folders team_folders_items = ca_service.content.get_content_items(content_id='team_folders') print(team_folders_items)
head on to github.
Jokes aside, this code is quite raw & unpolished and far from best Python even I am capable of (and I’m a bad pythonista). But it does work and I would’ve really appreciated if something like this existed when I started automating this up, so maybe it helps someone else as I doubt I’ll have enough time to work on it in near future.
Cognos Analytics is used for reporting in an operational system via embedding report URLs in the application screens.
There’s an application level security that defines what user can see what reports / URLs in the application itself and given the number of users (~1000) and reports (~500) replicating the same report level security in Cognos Analytics manually is a herculean task.
The solution was to:
Along the way we also did a namespace migration, which is always a lot of fun, but this time we used a few Python scripts on the same collection of wrappers to:
turned out quite neat. Not as complete as the migration tools from BSP or Motio, but did the trick on migrating thousands of users accross.
I’ve been using Cognos Analytics SDK for many many years and still have quite a few projects where I’m using it for populating CAM groups, so I know how trusted and reliable it is.
The comparison between SDK and REST API goes something like this:
Rest API Pro’s:
Rest API Con’s:
A collection of some gotcha’s and notes.
If you’re like me and don’t like accessing a
dispatcher:9300/api endpoint and would prefer a gateway endpoint, this statement
Requests cannot be sent to the external gateway (IIS or Apache); otherwise, an extra rewrite rule would be required to handle /api requests.
in official documentation is this configuration in IIS:
It’s signficantly faster to retrieve the full list of users from a namespace and store it for your script instead of searching for an individual user by id.
/users/identifier=Namespace call will return the list of all users in the namespace and in my sample of the namespace with ~4k users it takes about 10s to return the full list, whereas
/users/identifier=user_id takes about 2s, so returning the full list and searching it’s contents is a lot faster.
There’s no API call to see namespace folders in Cognos namespace, but if you know the id of the namespace folder, the
/roles/parent_id=namespace_folder_id returns the groups or roles within that folder.
So I had a conversation with the Cognos guru Paul Mendelson about the whole ‘should I use REST API for this task’ early in the project and he said a couple things that were invaluable during the development (thanks heaps for this Paul!):
if you’re stuck with what’s exposed in REST API, you can always trace what Cognos front end is calling in browser and execute the same calls, those service calls aren’t changing in years
This how namespace service was put together, you can see that browser runs a number of
/v1/namespaces calls to list objects in the namespace (groups, roles, namespace folders) when you navigate the
Accounts menu in the front end.
You do need to be logged in Cognos in a more explicit way than just the
session_key, which is where logging into Cognos Mashup Services allows you to get a proper
X-XSRF-Token that then can be used to access any
v1/ endpoint in Cognos.
I didn’t end up using namespace calls in the production version of the scripts, only to get the full list of namespace contents for the namespace migration.
And while I was rambling about exporting the contents of a Cognos Report to csv and reading the csv as source, he said
just use Cognos Mashup Services and read JSON of the report directly
which is a brilliant idea, CMS returns the JSON of the report if you run something along the lines of
from the report_data service.