The TM1 Admin Server

Learn all about the IBM® TM1® Admin Server here. To access the metadata of the TM1 Admin Server, use http://<adminserver>:5895/api/v1/$metadata or https://<adminserver>:5898/api/v1/$metadata.

Change the default value of the port number used by TM1 Admin Server

The TM1 Admin Server uses port 5895 for HTTP or port 5898 for HTTPS to communicate with the TM1 REST API. These values cannot be changed by using IBM Cognos Configuration. If you need to change the default values, you can modify the \<install directory>\configuration\cogstartup.xml file.

If you are using HTTPS, add the following lines:

<crn:parameter name="tm1AdminHTTPSPortNumber">
<crn:value xsi:type="xsd:unsignedShort">[xxxx]</crn:value> </crn:parameter>

If you are not using HTTPS, add the following lines, where [xxxx] is an available port number:

<crn:parameter name="tm1AdminHTTPPortNumber">
<crn:value xsi:type="xsd:unsignedShort">[xxxx]</crn:value> </crn:parameter>

Restart the TM1 Admin Server and verify the port number settings by specifying http://<tm1server>:5895/api/v1/Servers or https://<tm1server>:5898/api/v1/Servers in a local browser instance.

The response identifies the available servers in the following form:

{
    "@odata.context": "$metadata#Servers",
    "value": [
        {
            "Name": "a TM1 database",
            "SelfRegistered": true,
            "Host": "http://DESKTOP-RHJLSO4:8014",
            "IPAddress": "9.24.156.199",
            "IPv6Address": "",
            "PortNumber": 17414,
            "ClientMessagePortNumber": 0,
            "HTTPPortNumber": 8014,
            "IsLocal": false,
            "UsingSSL": false,
            "SSLCertificateID": null,
            "SSLCertificateAuthority": null,
            "SSLCertificateRevocationList": null,
            "ClientExportSSLSvrCert": false,
            "ClientExportSSLSvrKeyID": null,
            "AcceptingClients": true,
            "LastUpdated": "2020-01-07T22:17:56.778Z"
        }
    ]
}

Other available servers might also appear, but they don't display the HTTPPortNumber value unless these steps are done on the directories where they exist. The TM1 Admin Server provides the Server Root URL and displays the Servers entity set.

Manage a list of TM1 databases on the TM1 Admin Server

In TM1 Server version 11.7.0, you can set up one TM1 Admin Server that refers to the active TM1 databases for a model. All your users can point to the TM1 Admin Server and you can rapidly switch over from one TM1 database to another TM1 database. The TM1 Admin Server doesn't need to be restarted, which means that you can completely automate the failover to the backup system if a crash occurs on a TM1 database.

GET the list of databases that are available

To see which databases are currently self-registered, you can retrieve the list of TM1 databases that are registered with the TM1 Admin Server. You can use GET against the ~/api/v1/Servers resource to find the list of all databases that are available.

GET http://<adminserver>:<adminserver_port>/api/v1/Servers

Example response body:

{
    "@odata.context": "$metadata#Servers",
    "value": [
        {
            "Name": "24retail",
            "SelfRegistered": true,
            "Host": "http://DESKTOP-RHJLSO4:8014",
            "IPAddress": "9.24.156.199",
            "IPv6Address": "",
            "PortNumber": 17414,
            "ClientMessagePortNumber": 0,
            "HTTPPortNumber": 8014,
            "IsLocal": false,
            "UsingSSL": false,
            "SSLCertificateID": null,
            "SSLCertificateAuthority": null,
            "SSLCertificateRevocationList": null,
            "ClientExportSSLSvrCert": false,
            "ClientExportSSLSvrKeyID": null,
            "AcceptingClients": true,
            "LastUpdated": "2020-01-09T13:44:04.566Z"
        },
        {
            "Name": "GO_New_Stores",
            "SelfRegistered": true,
            "Host": "https://DESKTOP-RHJLSO4:5010",
            "IPAddress": "9.24.156.199",
            "IPv6Address": "",
            "PortNumber": 45557,
            "ClientMessagePortNumber": 0,
            "HTTPPortNumber": 5010,
            "IsLocal": false,
            "UsingSSL": true,
            "SSLCertificateID": null,
            "SSLCertificateAuthority": null,
            "SSLCertificateRevocationList": null,
            "ClientExportSSLSvrCert": false,
            "ClientExportSSLSvrKeyID": null,
            "AcceptingClients": true,
            "LastUpdated": "2020-01-09T13:44:10.120Z"
        },
        {
            "Name": "GO_Scorecards",
            "SelfRegistered": true,
            "Host": "https://DESKTOP-RHJLSO4:44312",
            "IPAddress": "9.24.156.199",
            "IPv6Address": "",
            "PortNumber": 44321,
            "ClientMessagePortNumber": 0,
            "HTTPPortNumber": 44312,
            "IsLocal": false,
            "UsingSSL": true,
            "SSLCertificateID": null,
            "SSLCertificateAuthority": null,
            "SSLCertificateRevocationList": null,
            "ClientExportSSLSvrCert": false,
            "ClientExportSSLSvrKeyID": null,
            "AcceptingClients": true,
            "LastUpdated": "2020-01-09T13:44:09.360Z"
        },
        {
            "Name": "Planning Sample",
            "SelfRegistered": true,
            "Host": "https://DESKTOP-RHJLSO4:12354",
            "IPAddress": "9.24.156.199",
            "IPv6Address": "",
            "PortNumber": 12345,
            "ClientMessagePortNumber": 0,
            "HTTPPortNumber": 12354,
            "IsLocal": false,
            "UsingSSL": true,
            "SSLCertificateID": null,
            "SSLCertificateAuthority": null,
            "SSLCertificateRevocationList": null,
            "ClientExportSSLSvrCert": false,
            "ClientExportSSLSvrKeyID": null,
            "AcceptingClients": true,
            "LastUpdated": "2020-01-09T13:44:02.022Z"
        },
        {
            "Name": "proven_techniques",
            "SelfRegistered": true,
            "Host": "https://DESKTOP-RHJLSO4:5011",
            "IPAddress": "9.24.156.199",
            "IPv6Address": "",
            "PortNumber": 53333,
            "ClientMessagePortNumber": 0,
            "HTTPPortNumber": 5011,
            "IsLocal": false,
            "UsingSSL": true,
            "SSLCertificateID": null,
            "SSLCertificateAuthority": null,
            "SSLCertificateRevocationList": null,
            "ClientExportSSLSvrCert": false,
            "ClientExportSSLSvrKeyID": null,
            "AcceptingClients": true,
            "LastUpdated": "2020-01-09T13:44:10.173Z"
        },
        {
            "Name": "SData",
            "SelfRegistered": true,
            "Host": "https://DESKTOP-RHJLSO4:8010",
            "IPAddress": "9.24.156.199",
            "IPv6Address": "",
            "PortNumber": 12346,
            "ClientMessagePortNumber": 0,
            "HTTPPortNumber": 8010,
            "IsLocal": false,
            "UsingSSL": true,
            "SSLCertificateID": null,
            "SSLCertificateAuthority": null,
            "SSLCertificateRevocationList": null,
            "ClientExportSSLSvrCert": false,
            "ClientExportSSLSvrKeyID": null,
            "AcceptingClients": true,
            "LastUpdated": "2020-01-09T13:44:09.619Z"
        },
        {
            "Name": "MyDB",
            "SelfRegistered": true,
            "Host": "https://DESKTOP-RHJLSO4:5001",
            "IPAddress": "9.24.156.199",
            "IPv6Address": "",
            "PortNumber": 60042,
            "ClientMessagePortNumber": 0,
            "HTTPPortNumber": 5001,
            "IsLocal": false,
            "UsingSSL": true,
            "SSLCertificateID": null,
            "SSLCertificateAuthority": null,
            "SSLCertificateRevocationList": null,
            "ClientExportSSLSvrCert": false,
            "ClientExportSSLSvrKeyID": null,
            "AcceptingClients": true,
            "LastUpdated": "2020-01-09T13:44:09.475Z"
        }
    ]
}

GET details for a specific database

You can do a GET against a specific database, for example, ~/api/v1/Servers('<database_name>'), to retrieve details of that database.

GET http://<adminserver>:<adminserver_port>/api/v1/Servers('<database_name>')

Example response body for GET http://<adminserver>:5895/api/v1/Servers('Sdata')

{
    "@odata.context": "$metadata#Servers/$entity",
    "Name": "SData",
    "SelfRegistered": true,
    "Host": "https://DESKTOP-RHJLSO4:8010",
    "IPAddress": "9.24.156.199",
    "IPv6Address": "",
    "PortNumber": 12346,
    "ClientMessagePortNumber": 0,
    "HTTPPortNumber": 8010,
    "IsLocal": false,
    "UsingSSL": true,
    "SSLCertificateID": null,
    "SSLCertificateAuthority": null,
    "SSLCertificateRevocationList": null,
    "ClientExportSSLSvrCert": false,
    "ClientExportSSLSvrKeyID": null,
    "AcceptingClients": true,
    "LastUpdated": "2020-01-09T13:54:10.343Z"
}

POST a database to your list of available TM1 databases

You can add another TM1 database to your list of available databases. POST changes to the database list on the TM1 Admin Server as a collection of Server entities.

POST http://<adminserver>:<adminserver_port>/api/v1/Servers

Example body with a database to add:

{
    "Name":"MyModel1",
    "IPAddress":"172.20.10.10",
    "PortNumber":12345,
    "UsingSSL": true,
    "ClientMessagePortNumber":61098,
    "HTTPPortNumber":12999,
    "ClientExportSSLSvrCert":true,
    "ClientExportSSLSvrKeyID":"whateverExportSSLSvrKeyID",
    "AcceptingClients":true
}

Example response body for POST, which shows defaults applied

{
    "@odata.context": "$metadata#Servers/$entity",
    "Name": "MyModel1",
    "SelfRegistered": false,
    "Host": null,
    "IPAddress": "172.20.10.10",
    "IPv6Address": "",
    "PortNumber": 12345,
    "ClientMessagePortNumber": 61098,
    "HTTPPortNumber": 12999,
    "IsLocal": false,
    "UsingSSL": true,
    "SSLCertificateID": null,
    "SSLCertificateAuthority": null,
    "SSLCertificateRevocationList": null,
    "ClientExportSSLSvrCert": true,
    "ClientExportSSLSvrKeyID": "whateverExportSSLSvrKeyID",
    "AcceptingClients": true,
    "LastUpdated": "2020-01-09T22:09:19.838Z"
}

PATCH a database to your list of available TM1 databases

Use PATCH to upsert (insert or update) a database to your list of available databases. PATCH changes to the database list on the TM1 Admin Server as a collection of Server entities.

PATCH http://<adminserver>:<adminserver_port>/api/v1/Servers

Example body with a database to insert or update:

Some properties are not required in the body. The response body shows you the defaults that are applied.

{
    "Name": "MyModel2",
    "IPAddress":"172.20.10.10",
    "PortNumber":12345,
    "UsingSSL":false
}

Example response body for PATCH, which shows defaults applied

{
    "@odata.context": "$metadata#Servers/$entity",
    "Name": "MyModel2",
    "SelfRegistered": false,
    "Host": null,
    "IPAddress": "172.20.10.10",
    "IPv6Address": "",
    "PortNumber": 12345,
    "ClientMessagePortNumber": 0,
    "HTTPPortNumber": 0,
    "IsLocal": false,
    "UsingSSL": false,
    "SSLCertificateID": null,
    "SSLCertificateAuthority": null,
    "SSLCertificateRevocationList": null,
    "ClientExportSSLSvrCert": false,
    "ClientExportSSLSvrKeyID": null,
    "AcceptingClients": false,
    "LastUpdated": "2020-01-09T13:51:13.770Z"
}

PATCH or DELETE a specific TM1 database

You can PATCH updates to individual TM1 databases or DELETE individual TM1 databases only if they were added using the TM1 REST API. Both of these requests use the same format.

The request body for a PATCH to an individual database cannot have the Name property because this property is implied by the URL.

PATCH http://<adminserver>:<adminserver_port>/api/v1/Servers('<database_name>')

{
    "IPAddress":"172.20.10.10",
    "PortNumber":12345,
    "UsingSSL":false
}

You don't need a request body to DELETE an individual database.

DELETE http://<adminserver>:<adminserver_port>/api/v1/Servers('<database_name>')