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.

Project background

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:

• create a Cognos report based on the operational system security tables that lists < users | what reports they have access to >
• Create a script that would
  • Read the data of this report
  • Create user groups and update members
  • assign report security accordingly

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:

• copy users from source to target namespace
• copy user profiles & my folders
• replicate the groups & roles memberships

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.

Cognos SDK vs REST API

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:

SDK Pro’s:

• Proven and stable with a large number of samples all around

SDK Con’s:

• Requires a Cognos Analytics installation to run from
• Requires a JDK to develop

Rest API Pro’s:

• Doesn’t require Cognos Analytics to run – can be executed from anywhere, eg a lambda / cloud function
• Performance – I found it to be a lot faster than SDK to run, mainly due to ‘bulk’ operations (adding a list of users to a groupd is a single call). SDK can be quite fast as well, but most of the default samples are ‘single operation’ focused (e.g. adding 1 user), so you end up with a fairly sluggish solutions if they’re built on sample code.

Rest API Con’s:

• Nowhere near ‘full’ coverage of methods – this is the biggest challenge, the officially supported list of methods has some pretty glaring omissions (for example, my personal favourite of not being able to see namespace folders in the namespace) and while there are workarounds for it (see Groups and Roles limitations), it’s quite jarring. So check the API method coverage before selecting it or go down the ‘workaround’ route
• Lack of samples and documentation can be a bit obscure – there’s a very long discussion on IBM communities on ‘how to login in REST API’ that tells you a lot about how simple REST API is to pick up and get going :)

Using CA REST API

A collection of some gotcha’s and notes.

Configuring gateway url rewrite

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:

Working with users in a namespace

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.

Groups and Roles or other REST API limitations

There’s no API call to see namespace folders in Cognos namespace, but if you know the id of the namespace folder, the /groups/parent_id=namespace_folder_id or /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

ca_service.report_data.run_report_sync(reportid='id',fmt='DataSetJSON')

from the report_data service.