Cognos TM1 Web API session token login

Use the session token login approach to uniquely identify your Cognos® TM1® Web session. This login approach is recommended for the URL API and required for the JavaScript library.

The session token login returns a unique session token that represents a login session for a specific user, Admin host, and TM1 server combination.

You can use the JavaScript XMLHttpRequest API to send an HTTP login request to the Cognos TM1 Web server. The session token is then returned in a JavaScript Object Notation (JSON) format from the request. After you receive the session token, you can then use it when you open TM1 Web objects.

If a timeout occurs with your HTTP session from inactivity, the Cognos TM1 Web session and related token are no longer valid.

Session token login process

The overall process for logging in with a session token includes the following steps.

  1. If you are using the URL API, set the LegacyUrlApiSessionDiscoveryEnabled configuration parameter in the tm1web_config.xml file.
    Note: This configuration parameter is not needed if you are using the JavaScript library.
  2. Assemble a set of parameters for the login request that are based on the type of authentication you are using with Cognos TM1.
  3. Post the login request to the Cognos TM1 Web server by using the JavaScript XMLHttpRequest API or other similar approach.
  4. Process the JSON response to get the returned session token.
  5. Use the session token when you open Websheet and CubeViewer objects.

Configuration parameter for session token login

If you are using the session token login approach with the URL API, you must set the LegacyUrlApiSessionDiscoveryEnabled configuration parameter in the tm1web_config.xml file to False.

This parameter enables the URL API session to be reused based on the specified admin host, TM1 server, and (optional) user name.

<add key="LegacyUrlApiSessionDiscoveryEnabled" value="False"/>

Login request parameters

Use the session token approach by sending a set of parameters in the request for the type of authentication that you are using with Cognos TM1.

For TM1 standard authentication and integrated login, use the following parameter format:

  • param0=TM1_Admin_host
  • param1=TM1_server_name
  • param2=username
  • param3=password

For example:

param0=localhost&param1=SData&param2=admin&param3=apple

If you are using IBM® Cognos Business Intelligence security for authentication, use the following format to include a value for the camPassport:

  • param0=TM1_Admin_host
  • param1=TM1_Server_name
  • param2=camPassport

JSON reply for session token login

The results of the login request are returned in a JSON formatted string.

If the login request is successful, the reply is returned in the following format.

{ 
	"reply":{
		"adminHost":adminHost,
		"sessionToken":sessionToken,
		"tm1Server":tm1Server,
		"username":username
	}
}

For example:

{ 
	"reply":{
		"adminHost":"localhost",
		"sessionToken":"06974cbd-ff2d-408b-8181-87bddd3f9048",
		"tm1Server":"Planning Sample",
		"username":"admin"
	}
}

If the login request is not successful, the following reply is returned.

{ "reply":null}

Example

The following example uses the JavaScript XMLHttpRequest API to post a login request to the TM1 Web server and retrieve the assigned session token.
<script type="text/javascript">

function login() {
   var xhr = new XMLHttpRequest();
   xhr.open("POST", "http://localhost:9510/tm1web/dwrx/jsonp/TM1Service/login", true);
   xhr.setRequestHeader("Content-type", "application/x-www-form-urlencoded");
   xhr.onload = function() {
      var response = JSON.parse(xhr.responseText).reply;

      if(response != null) {
         var sessionToken = response.sessionToken;
         console.debug("Session token: " + sessionToken);
      }
      else {
         console.error("Login failed.");
      }
   }

   var params = "param0=localhost&param1=Planning+Sample&param2=admin&param3=apple";

   xhr.send(params);
};

</script>
Parent topic: Cognos TM1 Web API