Demystify the differences between the IBM Cognos SDK and Mashup Service. If you are facing a custom solution centering around your IBM Cognos BI, then this article will help align you with the correct solution.
Comparing IBM Cognos Mashup Services with the IBM Cognos SDK
The Fable of Foo and Bar
Once upon a time there was a Big Blue land called Cognos. In the land of Cognos lived two brothers named Foo and Bar. They had grown old enough to leave their sleepy home towns in search of success. Their parents suggested that they visit a few cities in order to find the best fit. They packed their bags and hopped on the BiBus.
Their first destination was the bustling mega-city of SDKopolis. It was filled with every opportunity that one might seek. Upon arrival in the city they first checked with the local Cognos Port Authority to make sure that they met the necessary requirements and held the proper SDK license. They set off to discover the city. SDKopolis was a true marvel. For those willing to put forth the effort, opportunity was abundant. With such opportunity came a corresponding amount of complexity.
Their second destination was the newer area of Mashupville. This was a much smaller town with a relaxed, simpler vibe. It had all of the basic services that one would expect.
While sitting in a Mashupville cafe, Foo remarked enthusiastically to his Brother. “I love it here in Mashupville! It’s perfect! Life is so laid back. It seems that everything I need is right here for the taking. If I were to go to SDKopolis it would take me twice as long to get to the same goal”.
Bar, who was always a patient and critical person, waited until he was sure that his brother had finished; then rebutted, “Mashupville is a nice place indeed. It does offer easy access to all the basic necessities. However, I need something more. SDKopolis would give me the opportunity that just doesn’t exist in Mashupville. I have accepted that there is more effort involved. I think it is completely justified.”
The two brothers finished their meal, shook hands, and parted ways for their respective cities. Both were content (for themselves and the other) that they had made the choice that would allow them to thrive.
I recall my first exposure to the Cognos Mashup Service was a webinar delivered by IBM. The presenter introduced samples of the Mashup services, discussed its potential, and briefly talked about how to use it from a development perspective. There was one bullet point on a single slide that conveyed the idea that “Mashup was NOT a replacement for the SDK”. The statement was made and without skipping a beat to elaborate, the presentation continued. Later in the very same meeting a number of examples were demonstrated. They showed how Mashup solved some of the same problems that had traditionally been solved with the SDK. Clearly this was a contradiction of the earlier statements.
It took quite a bit of personal experience with the Mashup service to truly understand the bullet point declaration. Starting with the little parable above this article will help to distinguish the two technologies from one another.
Now, there is one point of qualification that needs to be made before we get underway. “The Cognos SDK” that we’ll use for comparison here refers to the SOAP based services which are exposed by Cognos, and does not include the URL Based interface.
The IBM presenter for the aforementioned slide containing that echoing statement “Mashup is not a replacement for the SDK” was referring to the functional aspects of the two solution sets. Functionality is a key comparator. Mashup and SDK can also be measured against each other on a number of other criteria, such as complexity and system requirements
Software Requirements and Licensing
This is a simple starting point for analysis which can best be illustrated with a side-by-side comparison of the prerequisites one needs to satisfy (before developing code) in order to use the SDK and Mashup Service.
| Cognos SDK | Cognos Mashup Service | |
| Minimum IBM Cognos BI Version | All versions since ReportNet 1.0 | IBM Cognos 8.4.1 or later |
| Consumers | SOAP over HTTP(S) | SOAP or REST URL over HTTP(S) |
| Endpoints | Gateway or Dispatcher | REST confers with the Gateway only while SOAP Mashup can be targeted at either the Gateway or Dispatcher |
| Licensing | SDK License Required | SDK License Required |
The most heavily weighted factor within the system requirements comparison is the minimum Cognos version. This would most certainly affect the choice of whether to use Mashup or SDK for a custom solution. The effort and expense of upgrading to (at least) 8.4.1 could outweigh the benefits provided by using the Mashup service.
Functional Capabilities
On the surface both are application programming interfaces for interacting with IBM Cognos. The intent of the Mashup service is narrowly focused towards running reports and obtaining report output. It provides many of the necessary interfaces that one would consider part of the report execution lifecycle:
- User Authentication (login/logout)
- Prompt Handling
- Report Execution
- Obtaining Output
- Drill Behavior
- Burst Output Selection
Along the line of report execution the Mashup service differs from the SDK. The SDK allows for advanced run options to be specified where the Mashup service does not. Examples of these are:
- Save as (and Save as View)
- Report scheduling
- Use of certain output formats
- A single execution request that generates output in multiple formats
The Cognos SDK provides the means to perform all of the actions afforded to the Mashup service. In addition to those functions it can also manipulate every lever and knob present in Cognos BI. The list of functions that it exposes is very broad, and fills a manual that runs roughly three thousand pages. However, for the sake of brevity these are some of the most commonly used features of the SDK.
- Report Execution and Output Acquisition (including the advanced execution options missing from the Mashup service)
- Report Authoring and Validation
- Framework Model Creation and Publication
- Scheduling
- Manipulation of Cognos Content
- Security Configuration
This begs another question, “If the SDK can do everything that the Mashup Service does and more, then why ever use Mashup?” This provides a perfect segue into comparing the two services based on the other criteria.
Complexity
The Cognos Mashup Service was designed with ease of use in mind. Its creators looked at the current trends in programming and went with a standard approach, yielding both SOAP and REST style interfaces. Thus developers attempting to utilize the Mashup service need to be competent interacting with REST URL or SOAP based interfaces. The SDK is also SOAP based. So, there is some overlap there.
The learning curve for working with the Cognos SDK is steeper than that of the Mashup Service. This is due in part to the greater breadth of what can be accomplished with the SDK. Let’s examine this in greater detail. Below is a JUnit test case for Java based SDK code which runs an HTML report, gets the output then writes it to a file along with attachments. Those that do not want to see how the sausage is made can skip ahead to the “Complexity Summarized” portion of the article.
package com.motio.blog; import junit.framework.TestCase; import com.cognos.developer.schemas.bibus._3.*; import org.apache.commons.io.IOUtils; import org.junit.Test; import java.net.URL; import java.io.FileOutputStream; import java.io.OutputStream; public class BlogTestCase extends TestCase { @Test public void testRunBasicReport() throws Exception { String dispatcher = "http://cogserver:9300/p2pd/servlet/dispatch"; ContentManagerService_ServiceLocator cmServiceLocator = new ContentManagerService_ServiceLocator(); ContentManagerService_Port cmService = cmServiceLocator.getcontentManagerService(new URL(dispatcher)); ReportService_ServiceLocator reportServiceLocator = new ReportService_ServiceLocator(); ReportService_Port reportService = reportServiceLocator.getreportService(new URL(dispatcher)); //--- execute this report and save the output under ~/My Folders/Default Cognos Drill Source String reportPath = "/content/folder[@name='Samples']/folder[@name='Models']" + "/package[@name='GO Data Warehouse (query)']" + "/folder[@name='Report Studio Report Samples']" + "/report[@name='Total Revenue by Country']"; RunOptionStringArray roOutputFormat = new RunOptionStringArray(); roOutputFormat.setName(RunOptionEnum.outputFormat); String[] formats = new String[]{"HTML"}; roOutputFormat.setValue(formats); //--- we're going to save the output under a view in the current user's My Folders area... RunOptionSaveAs roSaveAs = new RunOptionSaveAs(); roSaveAs.setName(RunOptionEnum.saveAs); roSaveAs.setParentSearchPath("~/folder[@name='My Folders']"); roSaveAs.setObjectClass(ReportSaveAsEnum.reportView); RunOptionInt primaryWaitThreshold = new RunOptionInt(); primaryWaitThreshold.setName(RunOptionEnum.primaryWaitThreshold); primaryWaitThreshold.setValue(15); RunOptionInt secondaryWaitThreshold = new RunOptionInt(); secondaryWaitThreshold.setName(RunOptionEnum.secondaryWaitThreshold); secondaryWaitThreshold.setValue(15); Option[] runOptions = new Option[]{roOutputFormat, roSaveAs, primaryWaitThreshold, secondaryWaitThreshold}; //--- start the request... SearchPathSingleObject searchPath = new SearchPathSingleObject(reportPath); AsynchReply reply = reportService.run(searchPath, new ParameterValue[]{}, runOptions); //--- if the request doesn't complete immediately, go into a polling mode... while (reply.getStatus() != AsynchReplyStatusEnum.complete && reply.getStatus() != AsynchReplyStatusEnum.conversationComplete) { reply = reportService.wait(reply.getPrimaryRequest(), new ParameterValue[]{}, runOptions); } //--- the report execution has finished, now we'll query for xpath of the outputs AsynchDetail[] details = reply.getDetails(); AsynchDetailReportOutput detail = (AsynchDetailReportOutput) details[0]; BaseClass[] reportVersions = detail.getOutputObjects(); ReportVersion reportVersion = (ReportVersion) reportVersions[0]; PropEnum[] properties = new PropEnum[]{PropEnum.dataSize, PropEnum.data, PropEnum.searchPath}; QueryOptions queryOptions = new QueryOptions(); queryOptions.setDataEncoding(EncodingEnum.base64); SearchPathMultipleObject outputSearchPath = new SearchPathMultipleObject(reportVersion.getSearchPath().getValue() + "/output"); BaseClass[] outputs = cmService.query(outputSearchPath, properties, new Sort[]{}, queryOptions); Output output = (Output) outputs[0]; FileOutputStream localCopyOfFile = new FileOutputStream("SDK Test.html"); localCopyOfFile.write(output.getData().getValue()); SearchPathMultipleObject graphicSearchPath = new SearchPathMultipleObject(output.getSearchPath().getValue() + "/graphic"); outputs = cmService.query(graphicSearchPath, properties, new Sort[]{}, queryOptions); for (int i = 0; i < outputs.length; i++) { Graphic graphicOutput = (Graphic) outputs[i]; OutputStream fos = new FileOutputStream("SDKTest_graphic_" + i + ".png"); fos.write(graphicOutput.getData().getValue()); IOUtils.closeQuietly(fos); } } }
In contrast here is a basic HTML/JavaScript Mashup example which runs a synchronous report in HTML and inserts the output onto the page.
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <!--We are relying on prototype.js to make our lives easier. Get it from http://www.prototypejs.org/download--> <script type="text/javascript" src="js/prototype/prototype.js"></script> <script type="text/javascript"> function logon () { //authentication code goes here. This sample will work without it as long //as anonymous authentication is enabled or one has logged into Cognos //in this browser directly. } function runReport () { logon(); var response = getReportData(); var e = document.getElementById('report_body'); e.innerHTML = response.responseText; } function getReportData () { var restPath = 'http://cogserver/cognos8/cgi-bin/cognos.cgi/rds/reportData' + '/path/Public%20Folders/Samples/Models/GO%20Data%20Warehouse%20%28query%29/' + 'Report%20Studio%20Report%20Samples/Total%20Revenue%20by%20Country'; var response; var request = new Ajax.Request(restPath, { asynchronous : false, method : 'get', parameters : { async : 'OFF', fmt : 'HTML' }, onSuccess : function(aTransport) { response = aTransport; }, onFailure : function(aTransport) { var regex = /(RDS-ERR-)(d*)/; var err = aTransport.responseText.match(regex); if (err != null) { alert(aTransport.responseText); } } }); return response; } </script> <title>Motio Mashup Example</title> </head> <body onload="runReport()"> <div id="report_body">Loading...</div> </body> </html>
There are a few points of comparison that I would like to address with the samples. First off, the output rendered by these two samples is not exactly the same. The Mashup example yields a complete report output including images while the Junit based SDK test writes an html file and a .png file. If you open the html file you’ll notice styling and images are absent. This goes to illustrate another point. It is entirely possible to massage the SDK based example to function exactly like the Mashup version but it would require pulling all of the dependencies (Javascript, CSS, image attachments) and then replacing references in the html file to point to the local copies This is a heck of a lot more code to write and test compared to the Mashup example. An alternative would be to use the MHT output format instead of HTML, but MHT is not supported by all browsers. Even without the code to stitch together the missing pieces of the SDK version one can see that is more verbose. A developer must deal with a finer grain of object than that presented by the Mashup example.
Complexity Summarized
When considering Mashup services, the development team needs to be familiar with the Cognos report execution lifecycle. Also if the problem requires some custom rendering, then the development staff also requires competency in whatever rendering technology is chosen. For example, if the requirements stated that Cognos BI data needed to be rendered in an iPhone app store application, then knowledge of the iPhone development platform is critical. On a related side note; stay tuned for upcoming articles on using Mashup to bring report data to rich internet applications and mobile devices.
On the other hand, any Cognos related requirement that surpasses the fairly narrow surface area of what Mashup affords would require use of the SDK. Therefore at least one person on the development team needs to have broad understanding of what capabilities are accessible through the SDK vs. Mashup. An example would be a problem that requires information to be dynamically inserted into a report at execution time. The solution to this problem would require development staff with the basic SOAP competency as well as an understanding of the report specification xml, and the relevant SDK methods pertaining to the report service and content management service.
Conclusion
If you are staring down the barrel of a custom solution involving Cognos (perhaps feeling a little like Foo or Bar), then this should help to inform as to what options are available. Also it should provide ample food for thought when weighing options. Here is a flowchart that will serve as a coarse guide as to which option is most suitable.
Hopefully, this leads you to the appropriate choice. If the magic eight ball still reads “answer unclear”, then consult with an SDK / Mashup expert such as Motio.
{{cta(‘0baecbe3-6f77-4b19-9269-013431220b2c’)}}
