TM1 .Net SDK/API

[Motyl]

Hi

Is there a .Net sdk for TM1.If so, where can I find it (with samples, and documentation)?

[Alan Kirk]

Is there a .Net sdk for TM1.If so, where can I find it (with samples, and documentation)?

When you were looking through the documentation before posting this (as per the Request for Assistance Guidelines), did you happen to notice the document titled "tm1_api.pdf"? Or, if you were doing it through soft versions and went to Help => Contents and Index in Server Explorer, the link titled "IBM Cognos TM1 API Guide"?

[Harvey]

I assume you mean an actual SDK, not just documentation on the API. Unfortunately, IBM does not provide such a thing, and barely supports using the COM API from .NET.

However, I wrote a blog article about Flow OLAP's .NET C# TM1 API starter kit. It's not exactly an SDK, but it does provide a basic working program and a .NET library that might be enough for you to get cracking.

The download is at the end of the blog article. You can get in contact via PM or the Flow website if you need any additional help, that's what we're here for!

[Motyl]

Harvey, thank you
Alan Kirk Yes, after i public post, i noticed that is documentation, sorry for a problem

[Harvey]

Welcome. Let me know if you build anything cool, I'm always interested to see what people do with the API -- that's why I do my best to make it more accessible to developers.

[Motyl]

OK

But, i have problem:

I cannot login to the tm1.
Aplication found TM1 server, but when i try to login, i always have "login attempt's failed'. In architect with this login is OK (login through tm1 login webpage, after clicking on server in architect).
Maybe problem is cognos (10.1 express) configuration?
Could you help me, i'm newbie with cognos?

[qml]

Maybe problem is cognos (10.1 express) configuration?

The problem is Cognos Express itself - it does not provide any API's, unlike its bigger brother TM1.

[Motyl]

Maybe problem is cognos (10.1 express) configuration?

The problem is Cognos Express itself - it does not provide any API's, unlike its bigger brother TM1.

What a pity, are you sure? I can get list of tm1 servers using api, but i couldn't connect to them.

[Alan Kirk]

Maybe problem is cognos (10.1 express) configuration?

The problem is Cognos Express itself - it does not provide any API's, unlike its bigger brother TM1.

What a pity, are you sure? I can get list of tm1 servers using api, but i couldn't connect to them.

QML would probably have more experience with CX than I do (but then, so do J Edgar Hoover and Cardinal Woolsey), so I'd be reluctant to doubt his counsel on this. Bear in mind that you're getting the list of servers from an Admin Server, not from a TM1 server, which are separate and distinct applications. It's not beyond the bounds of possibility that Iboglix has crippled the CX servers (as opposed to the Admin Servers) in a way that stops them from being usable for API purposes though I'll admit that it's the first I've heard of it. (Though I'll also admit that I don't pay a lot of attention to CX.)

Check this article to make sure that you've covered all of the bases in terms of making a connection. If you have you may be flogging a dead horse.

[qml]

My experience with Cognoss Express is very limited too, but from what I remember (and can be wrong about) one of its restictions is that you cannot use the API's. Not sure at the moment if the API libraries are bundled with the installer, but I wouldn't be surprised either way. This PMR seems to confirm what I'm saying i.e. someone has raised that they can't use the API even though it's documented, to which IBM's reply was something along the lines of: "well, it clearly shouldn't be documented then and we'll meake sure it's not in the next release".

[lotsaram]

I'm pretty sure the API restriction is a licensing as opposed to a practical constraint. (much like the CX RunTI verbot which is thankfully no longer as of 10.2)

The CX ICAS server formerly known as Xcelerator and now known as PM is identical to the TM1 server. The APIs should still work, there's no other way that the myriad of 3rd party products could possibly connect to the TM1 server that is CX PM if they didn't. It is just that as part of CX licensing as far as I understand it you are just supposed to use the toolkit that IBM provides (i.e. TM1 Excel, TM1 Web, Cognos Insight & Cognos BI) and not use (or build with API) any other UIs. Hence you aren't allowed to hook up Enterprise BI, Cognos or 3rd Party vendor, to CX. Kind of makes sense for a product aimed at mid-market but with all the power of the enterprise version.

If you have issues connecting it is most likely to be an issue with the CAM namespace. Unlike TM1 this is space and case sensitive.

Although many Cognos restrictions are licensing only I would prefer not to be on the wrong side of IBM's lawyers.

[Harvey]

It's definitely worth checking if it's legal to use the APIs with CX. I have only had one customer using CX and don't remember anything about the API in the licensing restrictions -- but that doesn't necessarily mean some undocumented ones weren't imposed. Don't break the law, kids.

If you're having trouble running the sample application in the Flow .NET C# TM1API Starter Kit, make sure you go into the app.config file and make sure the location of the TM1 api files is correct. By default, it should be "C:\Program Files\ibm\cognos\tm1_64\bin", but if you have a different location (which is probably the case for CX) you'll have to update this value. Once you have done that, the program should work.

Also note that you should point to the 32-bit version (usually the bin folder rather than bin64) of the dlls. I'm sure you could get the 64-bit version to work with some tweaking of the compilations settings, but I've never seen enough value in it to do so.

[Michel Zijlema]

.Net API is not exactly my area of expertise, but...
Could the issue not 'just' be the fact that CX uses CAM authentication and the .Net API is not capable of handling this or is handling this in an other way than expected?

Michel

[Alan Kirk]

.Net API is not exactly my area of expertise, but...
Could the issue not 'just' be the fact that CX uses CAM authentication and the .Net API is not capable of handling this or is handling this in an other way than expected?

I don't frickin' believe this.

Remember how these geniuses "forgot" to include the .Net API "Help" file in 10.1? And how they lied to... sorry, told me that they would put it up for download Real Soon Now (over six freaking months ago) and how it was going to be reinstated with 10.2?

Well, I just looked in my 10.2 folders and found that it wasn't there.

Ineptitude is one thing, but this is something else. For last July they snuck this piece of cr@p past us, which I missed at the time:

TM1 10.1.x and up releases

The dotNet documentation is no longer delivered with the TM1 Product in version 10 and higher.

Please choose to develop software with the TM1 API in C++ and Java only.

Are you ****ING KIDDING ME????

First of all, dear IBM, most TM1 programmers started out in Excel. Which means that their programming skills are VBA based, from which we go to VB, from which we go to VB DOT FREAKIN' NET, one of the most widely used freaking languages On. This. Freaking. Planet. That's the planet that we're on. Not necessarily the planet that those in charge of the direction of TM1 development these days are on.

Secondly, the "classic" API, which is what I presume that you Big Blue Einsteins were alluding to in your typically ham-fisted manner in the page quoted above, was intended for C, not C++. Read your own sodding documentation if you don't believe me. There are, it will surprise you to learn, differences between the two languages. C++ is an object oriented language that would be a better fit with, oh, I dunno, what was it again... oh, right, the also-object oriented .Net API, now I remember. (That having been said all of the documentation for the .Net API referred to its cousin C#, which I note that you also omit the mention of in your document. No mention of VB, no mention of C#. Couldn't have anybody writing in a Microsoft language now, could we? Newsflash: MS isn't going anywhere in the foreseeable future, and neither are those with MS-based skills, IBM. Except maybe to competing products if you persist in screwing them over. Learn to love the concept.)

Thirdly, {insert anatomically impossible suggestions here} that piece of {insert infinite stream of invective-based expletives here} Java and all who sail in her. If anyone chooses to use that security-holed, bug-ridden, update-every-day piece of garbage, that's their choice and they're welcome to it. I, however, do not wish to be forced down that path. (Two years later edit: "Even though I was, eventually.")

Fourthly, I'll come back to in a minute.

Anyway, having dug the file out of the remnants of my 9.5.2 install, I can confirm that it is supposed to support CAM authentication:

Applix.TM1.API Namespace > TM1ServerInfo Class : LoginUsingCAMNamespace Method
C#
C++/CLI nameSpace
CAM namespace. strUserID
User ID for logging-in to CAM server. strPassword
Password for logging-in. Logs into the TM1Server database server using a CAM namespace.
Syntax
Visual Basic (Declaration)
Public Function LoginUsingCAMNamespace( _
ByVal nameSpace As String, _
ByVal strUserID As String, _
ByVal strPassword As String _
) As TM1Server

Visual Basic (Usage) Copy Code
Dim instance As TM1ServerInfo
Dim nameSpace As String
Dim strUserID As String
Dim strPassword As String
Dim value As TM1Server

value = instance.LoginUsingCAMNamespace(nameSpace, strUserID, strPassword)

C#
public TM1Server LoginUsingCAMNamespace(
string nameSpace,
string strUserID,
string strPassword
)

Managed Extensions for C++
public: TM1Server* LoginUsingCAMNamespace(
string* nameSpace,
string* strUserID,
string* strPassword
)

C++/CLI
public:
TM1Server^ LoginUsingCAMNamespace(
String^ nameSpace,
String^ strUserID,
String^ strPassword

Parameters
nameSpace
CAM namespace.
strUserID
User ID for logging-in to CAM server.
strPassword
Password for logging-in.
Return Value
A TM1Server object that provides access to the resources of the database. If the login attempt is unsuccessful then null is returned.

Oh, fourth, that's right, fourth.

Given that they've pulled the documentation with nothing but a notice to that effect in some obscure page tossed onto the garbage dump that passes for IBM's web site, does anyone want to make a bet that they'll pull support for the whole .Net API (probably with a similar amount of notice) at some point in the future? (Which seems to be what they're hinting at with that not so cryptic little comment about how people should "choose" to develop only in C++ or Java; pah! Like it's a "choice" when options are removed.) And that they'll therefore similarly pull any support for VB/VB.Net APIs notwithstanding the number of people who still use the Excel interface? For after all, Java is our saviour, all hail Java! The point being... I'm not sure that I'd put a hellofalot of effort into developing tools in the .Net API if there's a risk of IBM pulling the rug out from under your feet and notifying you about it in a one liner on a nondescript web page in the middle of the Cyberspace equivalent of nowhere.

Now I grant you that there probably hasn't been a lot of development done using the .Net API, certainly not compared to the amount done using the classic API. And probably not even compared to the Java API, which I nonetheless suspect is not as widely used as IBM thinks it is; there are still a lot of places that follow the creed that if you don't need Java, you shouldn't install Java. However that's down to IBM shipping the .Net API in a half-birthed state with minimal functionality and even less real, useful documentation, not down to a lack of desire to connect to TM1 via as many routes as possible. Yeah, the .Net API was a screw up, albeit an occasionally useful screwup. And YOU screwed it up IBM. You throttled it in its cradle and ensured that it wouldn't be widely used by not giving it anywhere near enough functionality. For the record, killing it ain't fixing it.

I swear to the gods, I've been p*ssed with IBM before but this marks a new high water mark. I thought I'd better mention that as some of you may have missed the subtlety that I employed in the subtext above.

[Harvey]

Nice rant Alan, and I agree, it's a complete cock up on IBM's part.

However, while they might pull support for the C API at some point in the future (in the sense that they will cease to document it and encourage it's use) they surely cannot pull the functionality itself, as it's the way Perspectives and Performance Manager communicate with the server.

We can always use Dependency Walker to find out what functions are exposed, as detailed in my blog article, and it's not likely that massive changes will occur in the API anyway. Most of the additional functionality of late has been written into the client software rather than the API.

I've mentioned this before, so I'll mention it again here. I have a fully working, fairly comprehensive .NET API that I use to develop my Flow tools. Is there any interest in me providing this to others as an alternative to IBM's API? It would be some work to maintain and document it correctly, so I'd have to think about the commercial aspects, but I'm willing to look at it if there is interest.

At least it would remove a reliance on IBM for future products and tools...

[Alan Kirk]

Nice rant Alan, and I agree, it's a complete cock up on IBM's part.

However, while they might pull support for the C API at some point in the future (in the sense that they will cease to document it and encourage it's use) they surely cannot pull the functionality itself, as it's the way Perspectives and Performance Manager communicate with the server.

For now. This presupposes that there aren't future moves in other directions. Tomcat and Java have replaced IIS on the Web side, which is a pretty clear signal that nothing need be forever.

I've mentioned this before, so I'll mention it again here. I have a fully working, fairly comprehensive .NET API that I use to develop my Flow tools. Is there any interest in me providing this to others as an alternative to IBM's API? It would be some work to maintain and document it correctly, so I'd have to think about the commercial aspects, but I'm willing to look at it if there is interest.

Probably not much point expending the time unless it's just out of personal interest; as a product, it's already been done.

[Harvey]

Probably not much point expending the time unless it's just out of personal interest; as a product, it's already been done.

It's pretty different from the EasyAPI, which as I understand it is only usable from VB now?

What about an open source project, would anyone contribute?

[Motyl]

Harvey Location of dll in config files is ok (C:\Program Files (x86)\IBM\Cognos Express\bin), but when i want to connect, i always have "the login attempt failed",
I'm using cognos 10.1 express
Maybe problem is in configuration of cognos (default)?

[Harvey]

Hi Motyl,

I just did some testing on the API Starter Kit. The only issue I encountered was that the test program would exit unexpectedly while trying to get the server list. This was because the Visual Studio hosting process was enabled and presumably interfering with the TM1 API's memory management somehow.

It's possible your symptoms are caused by the same thing, so make sure you go into the project properties of the Flow.TM1StarterKitTest project, click on the "Debug" tab and uncheck the "Enable the Visual Studio hosting process" checkbox.

Once I did that, the sample ran correctly for me.

It's also worth noting that I have made no effort to support CAM security, so you'll need to disable this on the server you are trying to log into. I'm sure it's possible to support CAM, but when I was creating the sample, I didn't have any access to documentation about that, so omitted support.

[Motyl]

Sorry for maybe stupid question, but how to disable CAM security?