Preparing your TM1 / Planning Analytics model for the TM1 Rest API

You can find a lot of content on how to start using TM1’s REST API, for example here, here or here. However, to the best of our knowledge, until now there hasen’t been any guidance to be found anywhere on what changes you may need to make to an existing model to make it “REST API ready” or for that matter principles to keep in mind when creating a new TM1 model which will be consumed via REST API interfaces. We want to address this gap and give some solid practical advice for TM1 developers and administrators who might be wondering what to do in such situations.

For your application to communicate with your TM1 Server via REST API you need to make sure a unique port across all services running on the host server is allocated. You do this by setting the HTTPPortNumber parameter in the tm1s.cfg file. If this parameter is absent from the configuration file then the default http(s) port value is 5001. The HTTPPortNumber parameter works in conjunction with the UseSSL parameter. If UseSSL=true (the default value) then the TM1server will accept only secure https connections.

• The TM1 admin server uses the following tcp/ip ports which must be unblocked
  • 5495 & 5498 for non-http(s) (old APIs)
  • 5895 & 5898 for http(s) (REST API)
• The HTTPPortNumber parameter must be set to a unique value for each TM1 instance. These ports must also be unblocked in firewall settings
• If changing the http port you will need to recycle the TM1 instance since this parameter is static

To enable READ / (WRITE) access to a cube a group requires:

• READ / (WRITE) access to the cube in }CubeSecurity
• READ access to each dimension in the cube in }DimensionSecurity

And as far as the old APIs were concenred that was pretty much it. With the following exceptions for special use cases:

• READ access to the }PickList cube and }PickList dimension (should a }PickList cube exist)
• READ access to any }Drill_ processes relevant to cubes to which a group has at least READ access to

In addition to setting READ / WRITE cube securuty access and READ access to each dimension in the cube, for access via the the TM1 REST API to function properly, groups now also require:

• READ access to the }ElementAttributes dimension and }ElementAttributes cube for each dimension in the cube

Note: that strictly speaking explicit access to the attribute cube and attribute dimension isn’t absolutely necessary. A Rest based UI should still work without this, but things will work better and faster with this access. (This is due to a Rest API & OData quirk on requesting a single attribute value versus all attribute values for a given dimension.) And don’t forget that for many features MDX will be used, and quite often in advanced MDX explicit reference is made to attribute cubes. Without this access there will almost guaranteed be features that won’t work properly.

Also depending on the version of the TM1 server (and Rest API) and/or the version of PA Workspace you may also need:

• READ access to the }CubeDrill cube and }CubeDrillString dimension (should drill-through be defined for the cube)

The first several versions of the TM1 REST API supported only MDX Select queries and did not support MDX Set Expressions. Therefore the “native” way to query a dimension via the REST API is to query the dimension’s }ElementAttributes cube. In the initial versions of PAW the subset editor would actually fail if a dimension contained no attributes (and hence the }ElementAttributes cube was absent). Obviously, this functionality gap has since been closed but due to code legacy and backwards compatibility the default query method is always to use the }ElementAttributes cube if it exists. In any case without READ access to the respective attribute cube users will be unable to see any attribute values.

This leads to some recommended best practices when designing models which will be consumed via a TM1 REST API interface:

• All model dimensions should contain at least one attribute to ensure the existence of an }ElementAttributes cube
• Should a dimension otherwise have no attributes we recommend creating a “Caption” attribute for the dimension as type “String”

Many people don’t realize but the Caption attribute doesn’t have to be an alias. In fact it is better practice to make Caption a string as this will give you more flexibility and allow the application to be more user friendly. Even if values are not unique, Caption attributes work much the same as aliases for display purposes in all native REST API interfaces; if no caption is set then the principal name will be displayed, otherwise the caption.

This blog article is a condensed version of of an Apliqo UX Technote. The full technote also contains

1. a handy code snippet to automatically create dependent object permissions and
2. a troubleshooting guide to fix common permission issues in applications using the REST API.

You can find the full Technote here.