Version 11 Release 2

IBM Planning AnalyticsTM1 REST API

IBM

Note

Before you use this information and the product it supports, read the information in Chapter 10,“Notices,” on page 167.

Product Information

This document applies to IBM Planning Analytics Version 2.0 and might also apply to subsequent releases.

Licensed Materials - Property of IBM

Last updated: 2019-01-20© Copyright International Business Machines Corporation 2007, 2019.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract withIBM Corp.

Contents

Introduction......................................................................................................... ix

Chapter 1. Overview.............................................................................................. 1Conformance................................................................................................................................................1TM1 REST API introduction......................................................................................................................... 2

Syntax used in examples........................................................................................................................2Read from the model (HTTP GET)..........................................................................................................3Create an entity (HTTP POST)................................................................................................................ 3Update an entity (HTTP POST or PATCH)...............................................................................................4Delete an entity (HTTP DELETE)............................................................................................................ 4

References................................................................................................................................................... 5

Chapter 2. Installation and configuration............................................................... 7

Chapter 3. HTTP authentication............................................................................. 9

Chapter 4. Metadata............................................................................................ 11EDM hierarchy............................................................................................................................................ 11EntityContainer: API.................................................................................................................................. 23Entity types................................................................................................................................................ 24

Annotation............................................................................................................................................ 24ApplicationContextFacet......................................................................................................................25ApplicationContextFacetValue.............................................................................................................26Attachment...........................................................................................................................................26AttributeDefinition................................................................................................................................26Cellset................................................................................................................................................... 27CellsetAxis............................................................................................................................................ 27CellsetAxisTuple................................................................................................................................... 28CellsetCell.............................................................................................................................................28Chore.....................................................................................................................................................30ChoreReference....................................................................................................................................31ChoreTask............................................................................................................................................. 31Configuration........................................................................................................................................ 31Cube......................................................................................................................................................33CubeDrillthrough.................................................................................................................................. 35CubeReference..................................................................................................................................... 35Dimension.............................................................................................................................................35DimensionReference............................................................................................................................ 36Document............................................................................................................................................. 36DocumentReference............................................................................................................................ 37Drillthrough...........................................................................................................................................37Edge...................................................................................................................................................... 37Element.................................................................................................................................................38Entry......................................................................................................................................................39ErrorLogFile.......................................................................................................................................... 40Folder....................................................................................................................................................40Group.................................................................................................................................................... 40Hierarchy.............................................................................................................................................. 41Level......................................................................................................................................................43Link........................................................................................................................................................44LocalizedAttributes.............................................................................................................................. 44

iii

Logger................................................................................................................................................... 44MDXView...............................................................................................................................................45Member.................................................................................................................................................45MessageLogEntry................................................................................................................................. 46NativeView............................................................................................................................................47Process................................................................................................................................................. 48ProcessDebugContext..........................................................................................................................49ProcessDebugContextBreakpoint........................................................................................................50ProcessDebugContextDataBreakpoint................................................................................................ 50ProcessDebugContextLineBreakpoint.................................................................................................51ProcessDebugContextLockBreakpoint................................................................................................ 51ProcessDebugContextStackFrame...................................................................................................... 51ProcessDebugContextVariable............................................................................................................ 52ProcessErrorLog................................................................................................................................... 52ProcessReference.................................................................................................................................52RelationalDrillthrough.......................................................................................................................... 53SQLDataSource.....................................................................................................................................53Sandbox................................................................................................................................................ 53Server....................................................................................................................................................54ServerSettings...................................................................................................................................... 55Session..................................................................................................................................................55Subset...................................................................................................................................................56SubsetReference.................................................................................................................................. 57Thread...................................................................................................................................................57TransactionLogEntry............................................................................................................................ 58TupleMember....................................................................................................................................... 59User.......................................................................................................................................................60View...................................................................................................................................................... 61ViewReference......................................................................................................................................62

Complex types........................................................................................................................................... 62AccessSettings..................................................................................................................................... 62AdministrationSettings.........................................................................................................................62Attributes..............................................................................................................................................63AuditLogSettings.................................................................................................................................. 63AuthenticationSettings.........................................................................................................................64CAMSettings......................................................................................................................................... 64CAPISettings.........................................................................................................................................64CalculationComponent.........................................................................................................................65CellDescriptor.......................................................................................................................................65CellsetUpdate.......................................................................................................................................65ChoreTaskParameter............................................................................................................................ 66ClientSettings....................................................................................................................................... 66CubeUpdate..........................................................................................................................................66DebugLogSettings................................................................................................................................ 66DrillthroughRow....................................................................................................................................67EventLogSettings..................................................................................................................................67ExternalDatabaseSettings....................................................................................................................67FedCellDescriptor.................................................................................................................................67FeederTrace..........................................................................................................................................68FileRetrySettings.................................................................................................................................. 68HTTPSettings........................................................................................................................................68JavaSettings......................................................................................................................................... 68JobQueuingSettings............................................................................................................................. 68LDAPSettings........................................................................................................................................ 69LockingSettings.................................................................................................................................... 69MTQSettings......................................................................................................................................... 69MemorySettings................................................................................................................................... 70ModellingSettings.................................................................................................................................70

iv

NameValuePair..................................................................................................................................... 70NetworkSettings...................................................................................................................................71PerformanceSettings............................................................................................................................71ProcessDataSource.............................................................................................................................. 71ProcessDebugContextObjectLock....................................................................................................... 71ProcessExecuteResult..........................................................................................................................72ProcessParameter................................................................................................................................ 72ProcessSyntaxError..............................................................................................................................72ProcessVariable.................................................................................................................................... 73RuleSyntaxError................................................................................................................................... 73RulesSettings........................................................................................................................................73SSLSettings...........................................................................................................................................73ServerLogSettings................................................................................................................................ 74SpreadingSettings................................................................................................................................ 74StargateSettings................................................................................................................................... 74StartupSettings.....................................................................................................................................75SynchronizationSettings...................................................................................................................... 75TISettings............................................................................................................................................. 75TM1WebSettings.................................................................................................................................. 75ViewAxisSelection................................................................................................................................ 75ViewCalculationSettings...................................................................................................................... 75ViewTitle............................................................................................................................................... 76

Enumerated types......................................................................................................................................76AttributeType........................................................................................................................................ 76CalculationType.................................................................................................................................... 76CellStatus............................................................................................................................................. 76ChoreExecutionMode........................................................................................................................... 76ConflictResolution................................................................................................................................ 76ElementType.........................................................................................................................................77EncryptionFileType...............................................................................................................................77FIPSMode............................................................................................................................................. 77IPVersion.............................................................................................................................................. 77LogLevel................................................................................................................................................77MemberType.........................................................................................................................................77OracleErrorForceRowStatus................................................................................................................ 78ProcessDebugContextHitMode............................................................................................................78ProcessDebugContextLockMode......................................................................................................... 78ProcessDebugContextObjectLockScope............................................................................................. 78ProcessDebugContextStatus............................................................................................................... 78ProcessExecuteStatusCode................................................................................................................. 78ProcessProcedure................................................................................................................................ 79ProcessVariableType............................................................................................................................ 79SQLFetchType.......................................................................................................................................79SecurityMode........................................................................................................................................79ThreadType...........................................................................................................................................79UpdateOrder.........................................................................................................................................79UserType...............................................................................................................................................79ViewConsolidationOptimizationMethod.............................................................................................. 80

Functions....................................................................................................................................................80ControlCubes........................................................................................................................................80ControlDimensions...............................................................................................................................80Cube.DimensionsStorageOrder........................................................................................................... 80GetOIDCKeys........................................................................................................................................81Cellset.GetPartition.............................................................................................................................. 81MessageLog.......................................................................................................................................... 81ModelCubes..........................................................................................................................................82ModelDimensions.................................................................................................................................82TailMessageLog.................................................................................................................................... 82

v

TailTransactionLog................................................................................................................................82TransactionLog..................................................................................................................................... 83

Actions....................................................................................................................................................... 83Chore.Activate...................................................................................................................................... 83Dimension.AddAllLeavesHierarchy..................................................................................................... 83BeginChangeSet................................................................................................................................... 84Thread.CancelOperation...................................................................................................................... 84Cube.CheckFeeders..............................................................................................................................84Cube.CheckRules..................................................................................................................................85Session.Close........................................................................................................................................85Process.Compile...................................................................................................................................85CompileProcess....................................................................................................................................85ProcessDebugContext.Continue.......................................................................................................... 86Entry.Copy.............................................................................................................................................86Hierarchy.CreateSessionSubset...........................................................................................................86Chore.Deactivate.................................................................................................................................. 87Process.Debug......................................................................................................................................87DecryptDataFile....................................................................................................................................88DecryptDataModel............................................................................................................................... 88DeleteAnnotationArtifacts................................................................................................................... 88Sandbox.DiscardChanges.................................................................................................................... 88User.Disconnect....................................................................................................................................89EncryptDataFile.................................................................................................................................... 89EncryptDataModel................................................................................................................................89EndChangeSet...................................................................................................................................... 89MDXView.Execute.................................................................................................................................90NativeView.Execute..............................................................................................................................90Process.Execute................................................................................................................................... 90CubeDrillthrough.Execute.................................................................................................................... 91RelationalDrillthrough.Execute............................................................................................................91Chore.Execute...................................................................................................................................... 91ExecuteChore....................................................................................................................................... 92ExecuteCubeDrillthrough..................................................................................................................... 92ExecuteMDX......................................................................................................................................... 92ExecuteMDXSetExpression..................................................................................................................93ExecuteProcess.................................................................................................................................... 93ExecuteProcessWithReturn................................................................................................................. 93ExecuteRelationalDrillthrough.............................................................................................................94Process.ExecuteWithReturn................................................................................................................ 94Sandbox.Load....................................................................................................................................... 94Cube.Lock............................................................................................................................................. 95Dimension.Lock.................................................................................................................................... 95Sandbox.Merge.....................................................................................................................................95Entry.Move............................................................................................................................................ 96Sandbox.Publish...................................................................................................................................96RemoveOIDCKeyFromCache............................................................................................................... 97Cube.ReorderDimensions.................................................................................................................... 97RotateDataModelKey........................................................................................................................... 97Dimension.SaveAs................................................................................................................................97Hierarchy.SaveAs..................................................................................................................................98Subset.SaveAs......................................................................................................................................99Cellset.SaveViewAs.............................................................................................................................. 99Element.SetComponent.....................................................................................................................100Hierarchy.SetElement........................................................................................................................ 100Subset.SetElement............................................................................................................................ 101Chore.SetServerLocalStartTime........................................................................................................ 101ProcessDebugContext.StepIn............................................................................................................102ProcessDebugContext.StepOut......................................................................................................... 102

vi

ProcessDebugContext.StepOver....................................................................................................... 102Cube.TraceCellCalculation................................................................................................................. 102Cube.TraceFeeders.............................................................................................................................103UndoChangeSet..................................................................................................................................103Sandbox.Unload................................................................................................................................. 104Cube.Unlock....................................................................................................................................... 104Dimension.Unlock.............................................................................................................................. 104Cellset.Update....................................................................................................................................104Cube.Update.......................................................................................................................................105Update................................................................................................................................................ 105Cellset.UpdateCells............................................................................................................................106Cube.UpdateCells...............................................................................................................................107

Release notes.......................................................................................................................................... 107What's new in 11.4.0......................................................................................................................... 107What's new in 11.3.0......................................................................................................................... 107What's new in 11.2.0......................................................................................................................... 108What's new in 11.1.0.1...................................................................................................................... 108What's new in 11.1.0.0...................................................................................................................... 108What's new in 11.0.0.0...................................................................................................................... 109What's new in 10.2.2.7...................................................................................................................... 111What's new in 10.2.2.6...................................................................................................................... 111What's new in 10.2.2.5...................................................................................................................... 111What's new in 10.2.2.4...................................................................................................................... 112What's new in 10.2.2.3...................................................................................................................... 112What's new in 10.2.2.2...................................................................................................................... 112What's new in 10.2.2.1...................................................................................................................... 112What's new in 10.2.2.0...................................................................................................................... 113

Chapter 5. Representing TM1 data..................................................................... 115Discovering an OData service..................................................................................................................115EDM structure.......................................................................................................................................... 116Cubes and native views........................................................................................................................... 119

View a cube........................................................................................................................................ 119Display the available views in a cube................................................................................................ 119Get the specification of a view...........................................................................................................120Use options to view specific properties.............................................................................................121List dimensions in a cube...................................................................................................................121Expand dimensions and hierarchies in a cube.................................................................................. 122Use the Or operator to specify cube rules across hierarchies.......................................................... 123Delete a cube......................................................................................................................................125

Context dimensions and members......................................................................................................... 125Traverse a cube to view dimensions..................................................................................................125Create a dimension............................................................................................................................ 126Add a dimension to a cube.................................................................................................................127Delete a dimension............................................................................................................................ 127

Column and row dimensions...................................................................................................................128Expand columns and rows in a query................................................................................................128Use options to expand and filter details............................................................................................129Create a cube with dimensions and elements.................................................................................. 129

Cellsets.................................................................................................................................................... 131Find cell values in a cellset................................................................................................................ 131Run a view and expand the cellsets.................................................................................................. 132Get the cells of a cellset in multiple partitions..................................................................................132Preview a datasource.........................................................................................................................133Update a single cell value.................................................................................................................. 134Update many cell values.................................................................................................................... 135Delete a cellset ..................................................................................................................................136

vii

Elements.................................................................................................................................................. 136Retrieve elements by supplying either alias or invariant name........................................................136Update all elements in a static set.................................................................................................... 137

Chores...................................................................................................................................................... 138Folders and contents............................................................................................................................... 140Functions and actions..............................................................................................................................141Options and filters................................................................................................................................... 142

Batch options..................................................................................................................................... 142Pagination query options................................................................................................................... 143Filter expressions...............................................................................................................................144

Attributes and localization...................................................................................................................... 145Create Attributes and Captions for an entity.....................................................................................145Use TurboIntegrator functions.......................................................................................................... 148More information................................................................................................................................149

Chapter 6. Data spreading with the TM1 REST API..............................................151Spreading overview................................................................................................................................. 151

Spreading to a single leaf cell............................................................................................................ 151Spreading to a consolidated cell........................................................................................................151Spreading to a range.......................................................................................................................... 152After spreading is complete...............................................................................................................152

Spreading examples................................................................................................................................ 152Proportional spread, equal spread, and repeat................................................................................ 152Clear....................................................................................................................................................153Percent change...................................................................................................................................153Straight line........................................................................................................................................ 154Growth%.............................................................................................................................................154Relative proportional spread............................................................................................................. 154Relative percent adjustment..............................................................................................................155Repeat leaves..................................................................................................................................... 155Equal spread leaves........................................................................................................................... 156Applying holds....................................................................................................................................156

Spreading command codes.....................................................................................................................156

Chapter 7. TM1 settings..................................................................................... 161

Chapter 8. Troubleshooting................................................................................ 163

Chapter 9. Appendix 1: TM1 Admin Host.............................................................165

Chapter 10. Notices........................................................................................... 167©............................................................................................................................................................... 168

viii

Introduction

You can use the IBM® Cognos® TM1® REST API to perform create, read, update, and delete operations onTM1 data by using standards that are defined by OData Version 4 (http://www.odata.org/documentation/).

This document describes the semantics of the TM1 REST API and demonstrates how to use the TM1 RESTAPI by using samples and use cases.

Finding information

To find documentation on the web, including all translated documentation, access IBM Knowledge Center(http://www.ibm.com/support/knowledgecenter).

Audience

To use the IBM Cognos TM1 REST API effectively, you must be familiar with the following areas:

• TM1 and the TM1 architecture• Dimensional data and modeling terminology and concepts• OData Version 4• REST• HTTP programming (methods, headers, result codes)• Web authentication• JSON

For detailed information about how to interact with the TM1 REST API, see Chapter 5, “Representing TM1data,” on page 115.

Samples disclaimer

The Sample Outdoors Company, Great Outdoors Company, GO Sales, any variation of the SampleOutdoors or Great Outdoors names, and Planning Sample depict fictitious business operations withsample data used to develop sample applications for IBM and IBM customers. These fictitious recordsinclude sample data for sales transactions, product distribution, finance, and human resources. Anyresemblance to actual names, addresses, contact numbers, or transaction values is coincidental. Othersample files may contain fictional data manually or machine generated, factual data compiled fromacademic or public sources, or data used with permission of the copyright holder, for use as sample datato develop sample applications. Product names referenced may be the trademarks of their respectiveowners. Unauthorized duplication is prohibited.

Accessibility features

Accessibility features help users who have a physical disability, such as restricted mobility or limitedvision, to use information technology products.

This product does not currently support accessibility features that help users with a physical disability,such as restricted mobility or limited vision, to use this product.

Forward-looking statements

This documentation describes the current functionality of the product. References to items that are notcurrently available may be included. No implication of any future availability should be inferred. Any suchreferences are not a commitment, promise, or legal obligation to deliver any material, code, orfunctionality. The development, release, and timing of features or functionality remain at the solediscretion of IBM.

© Copyright IBM Corp. 2007, 2019 ix

x IBM Planning Analytics TM1 REST API

Chapter 1. OverviewThe IBM Cognos TM1 REST API provides an Open Data Protocol (OData) Version 4 compliant interface toan IBM Cognos TM1 server, which allows clients to query and update data sources that are hosted by theIBM Cognos TM1 Server.

The OData standard defines a set of rules and guidelines that are derived from common web technologiesthat include HTTP, REST, XML, and JSON. The OData standard provides a rich, interactive interface to datathat can be accessed by any OData-compliant HTTP application. The TM1 REST API meets theintermediate conformance level of the OData Version 4 protocol. For more information, see“Conformance” on page 1.

You can use the TM1 REST API to maintain a TM1 model, manage T1 processes, and query data that isstored in the model. For general information, see “TM1 REST API introduction” on page 2. For moreinformation about how to use the TM1 REST APIs, see Chapter 5, “Representing TM1 data,” on page 115.

With minimal configuration, the TM1 REST API provides developers with a standards-based approach towriting applications that query and update TM1 models. The Entity Data Model (EDM) defines the TM1data model so that OData clients can understand and manipulate the model. For more information, seeChapter 4, “Metadata,” on page 11.

The OData website, OData.org, is a comprehensive source for information about the OData standard. Youcan find documentation about the provider of an OData web service (also referred to as an ODataendpoint) and consumers of the OData service. The OData standard is described in the followingdocuments:

• OData Part 1: Protocol• OData Part 2: URL Conventions• OData Part 3: Common Schema Definition Language (CSDL)• OData JSON Format

You can learn about TM1 REST API conformance to the OData Version 4 standard in the followingsections.

ConformanceThe TM1 REST API meets the intermediate conformance level of the OData Version 4 protocol.

The OData Version 4 protocol describes three levels of conformance for OData services: minimal,intermediate, and advanced. The minimal conformance level specifies the minimum set of requirementsfor a service to be considered an OData-compliant service.

Non-updateable service compliance

The TM1 REST API meets all requirements of the Intermediate Conformance Level, as described insection 13.1.2 of the OData Protocol specification, for a non-updatable OData Service.

In addition to the intermediate level supported, the TM1 REST API also satisfies the followingrequirements from the Advanced Conformance Level:

• Items 1-8.• The following items from 9:

– i, ii, iii, v, and vi.

© Copyright IBM Corp. 2007, 2019 1

Updatable service compliance

The TM1 REST API is an Updatable service but does not meet all of the requirements to be considered anUpdatable OData service, as described in section 13.1.1 OData Minimal Conformance Level. It doessatisfy requirements 14, 15, 16, 19, 20, and 23.

Supported formats

The TM1 REST API supports the [OData-JSON] format.

Supported preferences

The TM1 REST API supports some of the Header Prefer values that are specified in the OData Version 4protocol.

Supported preferences include the following values:

• 8.2.8.6 Preference odata.track-changes (supported only on transaction and message logs)• 8.2.8.7 Preference return=representation and return=minimal• 8.2.8.8 Preference respond-async

Entity tag (ETag) support

The TM1 REST API provides weak ETags for Cube, Dimension, Hierarchy, ElementCollection,Element, Subset, Process, View, and Chore entities.

For more information about the ETag header field, see the following ODATA references:

• 2.3 ETag ODATA standards• 8.3.1 Response Header ETag

TM1 REST API introductionThe TM1 REST API supports create, read, update, and delete operations.

The TM1 REST API documentation provides examples that follow syntax guidelines. For more information,see “Syntax used in examples” on page 2.

Syntax used in examplesAll of the examples in the TM1 REST API documentation assume a service root URL as follows:

http://tm1server:8000/api/v1/

When a syntax example is shown, the resource path portion of the URL and any query options that mightbe shown must be appended to the service root URL. For example:

Cubes/$count

The full URL used to execute this operation includes all three parts:

• The service root URL• The resource path (in the following example, Cubes/)• Any query options, such as $filter, which returns the cubes that match the filter criteria (in this

example all cubes with more than five dimensions):

http://tm1server:8000/api/v1/Cubes?$filter=Dimensions/$count gt 5

2 IBM Planning Analytics TM1 REST API

Read from the model (HTTP GET)You can run a read operation on the containing set where you want to create a new entity. To understandthe data structure of an entity that you want to create, you can examine the $metadata document that isprovided by the service URL:

http://tm1server:8000/api/v1/$metadata

Note: The port number is specified in the HTTPPortNumber entry in the tm1s.cfg file in the modeldirectory.

The $metadata document describes the structure, or schema, of the Process entity, which is the typethat is created in the example that follows:

<EntityType Name="Process"> <Key> <PropertyRef Name="Name"/> </Key> <Property Name="Name" Nullable="false" Type="Edm.String"/> <Property Name="HasSecurityAccess" Nullable="true" Type="Edm.Boolean"/> <Property Name="PrologProcedure" Nullable="true" Type="Edm.String"/> <Property Name="MetadataProcedure" Nullable="true" Type="Edm.String"/> <Property Name="DataProcedure" Nullable="true" Type="Edm.String"/> <Property Name="EpilogProcedure" Nullable="true" Type="Edm.String"/> <Property Name="DataSource" Nullable="true" Type="ibm.tm1.api.v1.ProcessDataSource"/> <Property Name="Parameters" Type="Collection(ibm.tm1.api.v1.ProcessParameter)"/> <Property Name="Variables" Type="Collection(ibm.tm1.api.v1.ProcessVariable)"/> </EntityType>

In this example, a GET action returns the existing Process entities

GET /api/v1/Processes

The result context is $metadata#Processes, which is where the new Process entity is contained:

{ "@odata.context": "$metadata#Processes", "value": [ { "Name": "mover", "HasSecurityAccess": false, ...

Create an entity (HTTP POST)To create a new entity, use a POST operation and specify the structure of the new entity, which is based onthe rules that are defined in the schema. For example, the following POST operation creates a process:

POST /api/v1/Processes

{ "Name": "MyProcess", "Parameters": [ { "Name": "PStartDate", "Prompt": "Start Period?", "Value": "Jan-2003" } ]}

If the schema for the entity that you are creating defines a property as Nullable="false", the propertyis required and you must provide a value in your payload or the operation fails. In the following example,the Name property must be specified.

The response contains the structure of the newly created entity:

{ "@odata.context": "$metadata#Processes/$entity",

Overview 3

"Name": "MyProcess", "HasSecurityAccess": false, "PrologProcedure": "", "MetadataProcedure": "", "DataProcedure": "", "EpilogProcedure": "", "DataSource": { "Type": "None" }, "Parameters": [ { "Name": "PStartDate", "Prompt": "Start Period?", "Value": "Jan-2003" } ], "Variables": []}

Update an entity (HTTP POST or PATCH)To change a property in an existing entity to a new value, you can use a PATCH operation with the contextof the entity that you want to update.

In the following example, the server's metadata document specifies that a Process entity can have anoptional HasSecurityAccess property and that it can be set by using a Boolean value:

<EntityType Name="Process"> <Key> <PropertyRef Name="Name"/> </Key> <Property Name="Name" Type="Edm.String" Nullable="false"/> <Property Name="HasSecurityAccess" Type="Edm.Boolean" Nullable="true"/> ... </EntityType>

Because the HasSecurityAccess property is a Boolean type, the value (true or false) is not enclosedin quotation marks, which would identify the value as a string.

PATCH /api/v1/Processes('mover')

{ "HasSecurityAccess": true }

The response from the server displays the updated entity:

{ "@odata.context": "$metadata#Processes/$entity", "Name": "mover", "HasSecurityAccess": true, ... }

Delete an entity (HTTP DELETE)You can delete an entity only if you have the appropriate TM1 permissions to do so.

The following entities can be deleted:

• Attachment• Annotation• Cellset

Note: DELETE must be called on every Cellset generated as a result of an Execute request after it isno longer needed. If unused Cellset entities are not deleted, they continue to consume systemresources until the session is closed.

• Component

4 IBM Planning Analytics TM1 REST API

Note: DELETE on a Component deletes the relationship between the specified component and theparent's component.

• Cube• Dimension

Note: DELETE on a Dimension is only allowed if the dimension is no longer used in a cube.• Edge

Note: DELETE on an Edge deletes the relationship between two elements that are indicated by theedge.

• Element• Group• Process• Sandbox• Subset• User• View

A cell by itself is not an entity because you cannot execute a DELETE action on a cell. Cells representintersections between elements of all the dimensions in a cube. If you remove elements from anydimension, you delete the cells that are associated with those elements. If you want to delete, or remove,the value of a cell, update the value of the cell to NULL by using the PATCH operation.

ReferencesFor detailed information about how to interact with the TM1 REST API, you can use the following ODataspecifications.

• OData Version 4.0 Part 1: Protocol• OData Version 4.0 Part 2: URL Conventions• OData Version 4.0 Part 3: Common Schema Definition Language• OData JSON Format Version 4.0

Overview 5

6 IBM Planning Analytics TM1 REST API

Chapter 2. Installation and configurationAfter you install IBM Cognos TM1 with the procedures that are described in the Planning AnalyticsInstallation and Configuration documentation, you must enable the use of TM1 REST APIs.

The following procedure needs to be followed for every TM1 Server that you want to enable TM1 RESTAPIs for:

1. If HTTPPortNumber is not defined in your tm1s.cfg file, then port number "5001" will be assignedautomatically. You can manually define your HTTPPortNumber in the tm1s.cfg file using the followingsyntax:

HTTPPortNumber=[xxxx]

Where [xxxx] is a valid port number (typically 1-65535).2. Configure the UseSSL property, which defines whether a client needs to connect by using the HTTP or

HTTPS protocol. Valid settings are UseSSL=T or UseSSL=F.

Attention: This property is a shared setting. Turning off the use of SSL turns it off for all CognosTM1 clients, which allows them to connect to the server in an insecure mode.

3. Start your TM1 Server.4. Verify your configuration with a GET request to see whether you get a response. For example:

https://<fully_qualified_domain_name>/api/v1/

You can also test whether you get the EDM metadata back from your server by using the followingrequest:

https://<fully_qualified_domain_name>/api/v1/$metadata

You can also check that the TM1 Server that is hosting the model is running by using a tool thatmonitors HTTP traffic.

For more information, see the following resources:

• Planning Analytics Local Installation and Configuration documentation• OData Version 4.0 Part 2: URL Conventions/Service Root URL

© Copyright IBM Corp. 2007, 2019 7

8 IBM Planning Analytics TM1 REST API

Chapter 3. HTTP authenticationTo use the TM1 REST API, your client application needs to authenticate to the TM1 Server.

When you make a request without the appropriate authentication, the TM1 Server returns a 401Unauthorized response code and sets the WWW-Authenticate header to indicate the authenticationmethod that is supported by the server.

The IntegratedSecurityMode parameter that is set in the tms1.cfg file for each server specifieswhich authentication modes are supported by that server.

For more information about the IntegratedSecurityMode parameter, see the Planning Analytics LocalInstallation and Configuration documentation.

You can use the Logger and ServerSettings entities to retrieve and update TM1 settings. For moreinformation, see Chapter 7, “TM1 settings,” on page 161.

Supported security modes

The following security modes are supported for TM1 REST API clients:

Basic IntegratedSecurityMode=1

Standard TM1 authentication is mapped to HTTP Basic authentication where the user name andpassword are passed on to the TM1 Server.

WWW-Authenticate: Basic Realm="TM1"

The server expects an Authorization header in the following format:

Authorization: Basic base64(user:password)

Mixed (Windows Integrated Authentication and Basic) IntegratedSecurityMode=2

This mode mixes both TM1 standard authentication with Windows Integrated Authentication (WIA).

To be able to indicate to the client that both modes are supported, the server returns two WWW-Authenticate headers. Because it is the preferred authentication mode in this case, the header theWindows Integrated Authentication mode is returned first, and then, the header that provides basicTM1 authentication is returned.

Windows Integrated Authentication (Microsoft Windows only) IntegratedSecurityMode=3

The server supports Windows Integrated Authentication (WIA) only. In this case, the server followsSPNEGO-based Kerberos and NTLM HTTP Authentication as outlined in RFC-4559. The WWW-Authenticate response header is similar to the following example:

WWW-Authenticate: Negotiate

To authenticate, the server expects an Authorization header to start the authentication sequencein the following format:

Authorization: Negotiate base64(token)

The authentication process might require multiple round-trips to complete the authenticationsequence. Intermittent results are returned with a 401 Unauthorized again, setting the WWW-Authenticate header again to Negotiate, but this time followed by the base64 encoded token tobe used to continue the authentication process.

© Copyright IBM Corp. 2007, 2019 9

IBM Cognos BI or Cognos Authentication Manager (CAM) authentication (IntegratedSecurityMode=4or 5)

When the TM1 Server uses CAM authentication or a combination of CAM and Native authentication,the server authentication fault response header includes a CAM client URI for the client to use toobtain an authentication token (CAM Passport). This approach eliminates the need to return thesecurity mode to set up authentication negotiation.

If the server security mode is set to CAM, the WWW-Authenticate headers returned on an HTTPrequest where authentication fails or is not present include the ClientCAMURI that is specified intm1s.cfg file, which is necessary to log in.

The TM1 Server supports CAM authentication that is based on a CAM passport or CAM credentials (anamespace, user name and password pair). Therefore, the server returns a WWW-Authenticateheader as in:

WWW-Authenticate CAMPassport http://sottprismdev1.canlab.ibm.com:8080/ibmcognos/cgi-bin/cognos.cgi, CAMNamespace

The URI passed as a parameter for CAMPassport is the ClientCAMURI as configured for that TM1Server. This URI must point to a Cognos BI instance that can be used to authenticate against byfollowing the URI. For more information about authenticating against CAM and how to integrate withit, see the IBM Cognos BI Software Development Kit.

After successful authentication, the cam_passport can be passed to TM1 for authentication by usingthe following Authorization header format:

Authorization: CAMPassport cam_passport

If you know how to log in to CAM with credentials, you can send an Authorization header thatcontains a base64-encoded user name, password and CAM namespace pair such as:

Authorization: CAMNamespace base64(user:password:namespace)

The TM1 Server validates the passport or the CAM namespace credentials against the URL specifiedby ServerCAMURI in the tm1s.cfg file.

Session management

A browser cookie that contains a session ID gets set during the authentication process. This session IDcookie must be passed back to the server on every subsequent request in the HTTP request header.

By default, authenticated sessions time out after 20 minutes of inactivity. Setting theHTTPSessionTimeoutMinutes parameter in the tm1s.cfg file on the TM1 Server changes the defaulttimeout value. If a session times out, requests made with the previous session ID return 401Unauthorized.

Closing a session

To close a session, call the Close action on the Session object. If you are using 10.2.2 Fix Pack 5 orlater, you can use the ActiveSession singleton as the Session object.

If you are using a version earlier than 10.2.2 Fix Pack 5, you can log out of the current session (specifiedby the TM1SessionID cookie) by using the following request:

GET /api/logout

When the Close action or the logout request succeeds, the client must re-authenticate to accessprotected resources.

Note: In your browser, you might get the impression that the logout never happened. Browsers cache thecredentials and re-authenticate automatically when the next "401 Unauthorized" response is returned bythe server, which makes the re-authentication seamless.

10 IBM Planning Analytics TM1 REST API

Chapter 4. MetadataThe Entity Data Model (EDM) defines the TM1 data model that is based on OData Version 4.0 Part 3:Common Schema Definition Language (CSDL). It defines the TM1 data model in a common way so thatOData clients can understand and manipulate the model.

EDM hierarchyThe EDM hierarchy describes the relationship between TM1 entities, their properties, and their navigationproperties.

The EDM organizes entities into a hierarchy. Each entity, which is of some entity type, contains properties,each of which defines the data that the entity contains. An entity might also have navigation properties,which represent connections between entities.

EntityType: AnnotationProperties:

ID (Type: String)Text (Type: String)Creator (Type: String)Created (Type: DateTimeOffset)LastUpdatedBy (Type: String)LastUpdated (Type: DateTimeOffset)

Navigation properties:ApplicationContext (Type: ApplicationContextFacetValue)DimensionalContext (Type: Member)Attachments (Type: Attachment)

EntityType: ApplicationContextFacetProperties:

Name (Type: String)Navigation properties:

Values (Type: ApplicationContextFacetValue)EntityType: ApplicationContextFacetValue

Properties:Value (Type: String)

Navigation properties:Facet (Type: ApplicationContextFacet)

EntityType: AttachmentProperties:

Name (Type: String)Description (Type: String)ContentType (Type: String)Size (Type: Int64)

EntityType: AttributeDefinitionProperties:

Name (Type: String)Type (Type: tm1.AttributeType)

© Copyright IBM Corp. 2007, 2019 11

EntityType: CellsetProperties:

ID (Type: String)Navigation properties:

Cube (Type: Cube)Axes (Type: CellsetAxis)Cells (Type: CellsetCell)

Bound functions:GetPartition

Bound actions:SaveViewAsUpdateUpdateCells

EntityType: CellsetAxisProperties:

Ordinal (Type: Int32)Cardinality (Type: Int32)

Navigation properties:Hierarchies (Type: Hierarchy)Tuples (Type: CellsetAxisTuple)

EntityType: CellsetAxisTupleProperties:

Ordinal (Type: Int32)Navigation properties:

Members (Type: TupleMember)EntityType: CellsetCell

Properties:Ordinal (Type: Int64)Status (Type: tm1.CellStatus)Value (Type: PrimitiveType)FormatString (Type: String)FormattedValue (Type: String)Updateable (Type: Int32)RuleDerived (Type: Boolean)Annotated (Type: Boolean)Consolidated (Type: Boolean)NullIntersected (Type: Boolean)Language (Type: Int32)HasPicklist (Type: Boolean)PicklistValues (Type: String))HasDrillthrough (Type: Boolean)

Navigation properties:DrillthroughScripts (Type: Drillthrough)Members (Type: Member)

12 IBM Planning Analytics TM1 REST API

EntityType: ChoreProperties:

Name (Type: String)StartTime (Type: DateTimeOffset)DSTSensitive (Type: Boolean)Active (Type: Boolean)ExecutionMode (Type: tm1.ChoreExecutionMode)Frequency (Type: Duration)Attributes (Type: tm1.Attributes)

Navigation properties:LocalizedAttributes (Type: LocalizedAttributes)Tasks (Type: ChoreTask)

Bound actions:ActivateDeactivateExecuteSetServerLocalStartTime

EntityType: ChoreReferenceNavigation properties:

Chore (Type: Chore)EntityType: ChoreTask

Properties:Step (Type: Int64)Parameters (Type: Collection(tm1.ChoreTaskParameter))

Navigation properties:Process (Type: Process)Chore (Type: Chore)

EntityType: ConfigurationProperties:

ServerName (Type: String)AdminHost (Type: String)ProductVersion (Type: String)PortNumber (Type: Int32)ClientMessagePortNumber (Type: Int32)HTTPPortNumber (Type: Int32)IntegratedSecurityMode (Type: Boolean)SecurityMode (Type: String)PrincipalName (Type: String)SecurityPackageName (Type: String)ClientCAMURIs (Type: String))WebCAMURI (Type: String)ClientPingCAMPassport (Type: Int32)ServerCAMURI (Type: String)AllowSeparateNandCRules (Type: Boolean)DistributedOutputDir (Type: String)

Metadata 13

DisableSandboxing (Type: Boolean)JobQueuing (Type: Boolean)ForceReevaluationOfFeedersForFedCellsOnDataChange (Type: Boolean)DataBaseDirectory (Type: String)UnicodeUpperLowerCase (Type: Boolean)

EntityType: CubeProperties:

Name (Type: String)Rules (Type: String)DrillthroughRules (Type: String)LastSchemaUpdate (Type: DateTimeOffset)LastDataUpdate (Type: DateTimeOffset)Attributes (Type: tm1.Attributes)

Navigation properties:Dimensions (Type: Dimension)Views (Type: View)ViewAttributes (Type: AttributeDefinition)PrivateViews (Type: View)Annotations (Type: Annotation)LocalizedAttributes (Type: LocalizedAttributes)

Bound functions:DimensionsStorageOrder

Bound actions:CheckFeedersCheckRulesLockReorderDimensionsTraceCellCalculationTraceFeedersUnlockUpdateUpdateCells

EntityType: CubeDrillthroughBound actions:

ExecuteEntityType: CubeReference

Navigation properties:Cube (Type: Cube)

EntityType: DimensionProperties:

Name (Type: String)UniqueName (Type: String)AllLeavesHierarchyName (Type: String)Attributes (Type: tm1.Attributes)

14 IBM Planning Analytics TM1 REST API

Navigation properties:Hierarchies (Type: Hierarchy)DefaultHierarchy (Type: Hierarchy)HierarchyAttributes (Type: AttributeDefinition)LocalizedAttributes (Type: LocalizedAttributes)

Bound actions:AddAllLeavesHierarchyLockSaveAsUnlock

EntityType: DimensionReferenceNavigation properties:

Dimension (Type: Dimension)EntityType: Document

Properties:Size (Type: Int64)LastUpdated (Type: DateTimeOffset)Content (Type: Stream)

EntityType: DocumentReferenceNavigation properties:

Document (Type: Document)EntityType: Drillthrough

Properties:Name (Type: String)

EntityType: EdgeProperties:

ParentName (Type: String)ComponentName (Type: String)Weight (Type: Double)

Navigation properties:Hierarchy (Type: Hierarchy)Parent (Type: Element)Component (Type: Element)

EntityType: ElementProperties:

Name (Type: String)UniqueName (Type: String)Type (Type: tm1.ElementType)Level (Type: Int32)Index (Type: Int32)Attributes (Type: tm1.Attributes)

Navigation properties:Hierarchy (Type: Hierarchy)Parents (Type: Element)Components (Type: Element)

Metadata 15

Edges (Type: Edge)LocalizedAttributes (Type: LocalizedAttributes)

Bound actions:SetComponent

EntityType: EntryProperties:

ID (Type: String)Name (Type: String)Attributes (Type: tm1.Attributes)

Navigation properties:ContainedBy (Type: Folder)LocalizedAttributes (Type: LocalizedAttributes)

Bound actions:CopyMove

EntityType: ErrorLogFileProperties:

Filename (Type: String)Content (Type: Stream)

EntityType: FolderNavigation properties:

Contents (Type: Entry)PrivateContents (Type: Entry)

EntityType: GroupProperties:

Name (Type: String)Navigation properties:

Users (Type: User)EntityType: Hierarchy

Properties:Name (Type: String)UniqueName (Type: String)Cardinality (Type: Int32)Structure (Type: Int32)Visible (Type: Boolean)Attributes (Type: tm1.Attributes)

Navigation properties:Dimension (Type: Dimension)Elements (Type: Element)Edges (Type: Edge)Subsets (Type: Subset)PrivateSubsets (Type: Subset)SessionSubsets (Type: Subset)Members (Type: Member)AllMember (Type: Member)

16 IBM Planning Analytics TM1 REST API

DefaultMember (Type: Member)Levels (Type: Level)LocalizedAttributes (Type: LocalizedAttributes)ElementAttributes (Type: AttributeDefinition)SubsetAttributes (Type: AttributeDefinition)

Bound actions:CreateSessionSubsetSaveAsSetElement

EntityType: LevelProperties:

Number (Type: Int32)Name (Type: String)UniqueName (Type: String)Cardinality (Type: Int32)Type (Type: Int32)

Navigation properties:Hierarchy (Type: Hierarchy)Members (Type: Member)

EntityType: LinkProperties:

URL (Type: String)EntityType: LocalizedAttributes

Properties:LocaleID (Type: String)Attributes (Type: tm1.Attributes)

EntityType: LoggerProperties:

Name (Type: String)Level (Type: tm1.LogLevel)

EntityType: MDXViewProperties:

MDX (Type: String)Bound actions:

ExecuteEntityType: Member

Properties:Name (Type: String)UniqueName (Type: String)Type (Type: tm1.MemberType)Ordinal (Type: Int32)IsPlaceholder (Type: Boolean)Weight (Type: Double)Attributes (Type: tm1.Attributes)

Metadata 17

Navigation properties:Hierarchy (Type: Hierarchy)Level (Type: Level)Element (Type: Element)Parent (Type: Member)Children (Type: Member)LocalizedAttributes (Type: LocalizedAttributes)

EntityType: MessageLogEntryProperties:

ID (Type: Int64)ThreadID (Type: Int64)SessionID (Type: Int64)Level (Type: tm1.LogLevel)TimeStamp (Type: DateTimeOffset)Logger (Type: String)Message (Type: String)

EntityType: NativeViewProperties:

Columns (Type: Collection(tm1.ViewAxisSelection))Rows (Type: Collection(tm1.ViewAxisSelection))Titles (Type: Collection(tm1.ViewTitle))SuppressEmptyColumns (Type: Boolean)SuppressEmptyRows (Type: Boolean)FormatString (Type: String)

Bound actions:Execute

EntityType: ProcessProperties:

Name (Type: String)HasSecurityAccess (Type: Boolean)PrologProcedure (Type: String)MetadataProcedure (Type: String)DataProcedure (Type: String)EpilogProcedure (Type: String)DataSource (Type: tm1.ProcessDataSource)Parameters (Type: Collection(tm1.ProcessParameter))Variables (Type: Collection(tm1.ProcessVariable))Attributes (Type: tm1.Attributes)

Navigation properties:LocalizedAttributes (Type: LocalizedAttributes)ErrorLogs (Type: ProcessErrorLog)

Bound actions:CompileDebugExecute

18 IBM Planning Analytics TM1 REST API

ExecuteWithReturnEntityType: ProcessDebugContext

Properties:ID (Type: String)Status (Type: tm1.ProcessDebugContextStatus)LastActivityDuration (Type: Int64)ObjectLocks (Type: Collection(tm1.ProcessDebugContextObjectLock))Result (Type: tm1.ProcessExecuteResult)

Navigation properties:CurrentBreakpoint (Type: ProcessDebugContextBreakpoint)Process (Type: Process)CallStack (Type: ProcessDebugContextStackFrame)Breakpoints (Type: ProcessDebugContextBreakpoint)Thread (Type: Thread)

Bound actions:ContinueStepInStepOutStepOver

EntityType: ProcessDebugContextBreakpointProperties:

ID (Type: Int32)Enabled (Type: Boolean)HitMode (Type: tm1.ProcessDebugContextHitMode)HitCount (Type: Int64)Expression (Type: String)

EntityType: ProcessDebugContextDataBreakpointProperties:

VariableName (Type: String)EntityType: ProcessDebugContextLineBreakpoint

Properties:ProcessName (Type: String)Procedure (Type: tm1.ProcessProcedure)LineNumber (Type: Int32)

EntityType: ProcessDebugContextLockBreakpointProperties:

ObjectName (Type: String)ObjectType (Type: String)LockMode (Type: tm1.ProcessDebugContextLockMode)

EntityType: ProcessDebugContextStackFrameProperties:

ID (Type: String)Procedure (Type: tm1.ProcessProcedure)LineNumber (Type: Int32)RecordNumber (Type: Int32)

Metadata 19

Navigation properties:Process (Type: Process)Variables (Type: ProcessDebugContextVariable)

EntityType: ProcessDebugContextVariableProperties:

Name (Type: String)Value (Type: PrimitiveType)

EntityType: ProcessErrorLogProperties:

Timestamp (Type: DateTimeOffset)Content (Type: Stream)

EntityType: ProcessReferenceNavigation properties:

Process (Type: Process)EntityType: RelationalDrillthrough

Bound actions:Execute

EntityType: SQLDataSourceProperties:

Name (Type: String)Description (Type: String)

EntityType: SandboxProperties:

Name (Type: String)IsLoaded (Type: Boolean)IsActive (Type: Boolean)IsQueued (Type: Boolean)IncludeInSandboxDimension (Type: Boolean)

Bound actions:DiscardChangesLoadMergePublishUnload

EntityType: ServerProperties:

Name (Type: String)ProductVersion (Type: String)PortNumber (Type: Int32)ClientMessagePortNumber (Type: Int32)HTTPPortNumber (Type: Int32)UsingSSL (Type: Boolean)SecurityPackageName (Type: String)ServicePrincipalName (Type: String)IntegratedSecurityMode (Type: tm1.SecurityMode)

20 IBM Planning Analytics TM1 REST API

ClientCAMURI (Type: String)ClientPingCAMPassport (Type: Int32)

EntityType: ServerSettingsProperties:

ServerName (Type: String)Access (Type: tm1.AccessSettings)Administration (Type: tm1.AdministrationSettings)Modelling (Type: tm1.ModellingSettings)Performance (Type: tm1.PerformanceSettings)

EntityType: SessionProperties:

ID (Type: Int64)Context (Type: String)

Navigation properties:User (Type: User)Threads (Type: Thread)

Bound actions:Close

EntityType: SubsetProperties:

Name (Type: String)UniqueName (Type: String)Expression (Type: String)Attributes (Type: tm1.Attributes)

Navigation properties:Hierarchy (Type: Hierarchy)Elements (Type: Element)LocalizedAttributes (Type: LocalizedAttributes)

Bound actions:SaveAsSetElement

EntityType: SubsetReferenceNavigation properties:

Subset (Type: Subset)EntityType: Thread

Properties:ID (Type: Int64)Type (Type: tm1.ThreadType)Name (Type: String)Context (Type: String)State (Type: String)Function (Type: String)ObjectType (Type: String)ObjectName (Type: String)RLocks (Type: Int32)

Metadata 21

IXLocks (Type: Int32)WLocks (Type: Int32)ElapsedTime (Type: Duration)WaitTime (Type: Duration)Info (Type: String)

Navigation properties:Session (Type: Session)

Bound actions:CancelOperation

EntityType: TransactionLogEntryProperties:

ID (Type: Int64)ChangeSetID (Type: String)TimeStamp (Type: DateTimeOffset)ReplicationTime (Type: DateTimeOffset)User (Type: String)Cube (Type: String)Tuple (Type: String))OldValue (Type: PrimitiveType)NewValue (Type: PrimitiveType)StatusMessage (Type: String)

EntityType: TupleMemberProperties:

DisplayInfo (Type: Int32)DisplayInfoAbove (Type: Int32)

EntityType: UserProperties:

Name (Type: String)FriendlyName (Type: String)Password (Type: String)Type (Type: tm1.UserType)IsActive (Type: Boolean)Enabled (Type: Boolean)

Navigation properties:Groups (Type: Group)Sessions (Type: Session)

Bound actions:Disconnect

EntityType: ViewProperties:

Name (Type: String)Attributes (Type: tm1.Attributes)

Navigation properties:Cube (Type: Cube)LocalizedAttributes (Type: LocalizedAttributes)

22 IBM Planning Analytics TM1 REST API

EntityType: ViewReferenceNavigation properties:

View (Type: View)

EntityContainer: APIThe EntityContainer is the top-level container for the EDM.

It defines the resources that comprise the API, including entity sets, singletons, actions, and functions. Ifan item is defined in the EDM but is not defined within the API entity container, it is bound to anotherresource defined within the model.

Entity sets

• Annotations [tm1.Annotation]• ApplicationContextFacets [tm1.ApplicationContextFacet]• Cellsets [tm1.Cellset]• ChoreAttributes [tm1.AttributeDefinition]• Chores [tm1.Chore]• Contents [tm1.Folder]• CubeAttributes [tm1.AttributeDefinition]• Cubes [tm1.Cube]• DimensionAttributes [tm1.AttributeDefinition]• Dimensions [tm1.Dimension]• ErrorLogFiles [tm1.ErrorLogFile]• Groups [tm1.Group]• Loggers [tm1.Logger]• MemberSets [tm1.CellsetAxis]• MessageLogEntries [tm1.MessageLogEntry]• ProcessAttributes [tm1.AttributeDefinition]• ProcessDebugContexts [tm1.ProcessDebugContext]• Processes [tm1.Process]• SQLDataSources [tm1.SQLDataSource]• Sandboxes [tm1.Sandbox]• Sessions [tm1.Session]• Threads [tm1.Thread]• TransactionLogEntries [tm1.TransactionLogEntry]• Users [tm1.User]

Singletons

• ActiveConfiguration• ActiveSession• ActiveUser• Configuration• Server• StaticConfiguration

Metadata 23

Functions

• ControlCubes• ControlDimensions• GetOIDCKeys• MessageLog• ModelCubes• ModelDimensions• TailMessageLog• TailTransactionLog• TransactionLog

Actions

• BeginChangeSet• CompileProcess• DecryptDataFile• DecryptDataModel• DeleteAnnotationArtifacts• EncryptDataFile• EncryptDataModel• EndChangeSet• ExecuteChore• ExecuteCubeDrillthrough• ExecuteMDX• ExecuteMDXSetExpression• ExecuteProcess• ExecuteProcessWithReturn• ExecuteRelationalDrillthrough• RemoveOIDCKeyFromCache• RotateDataModelKey• UndoChangeSet• Update

Entity typesEntity types are structured records consisting of named and typed properties. Entity types contain a key.

AnnotationKey: ID

OpenType: true

An element that represents a single annotation.

An annotation applies a term to a model element and defines how to calculate a value for the termapplication.

Properties

24 IBM Planning Analytics TM1 REST API

ID

The ID of the annotation.

Type: Edm.StringNullable: false

Text

The text of the annotation.

Type: Edm.StringCreator

The creator of the annotation.

Type: Edm.StringCreated

The date that the annotation was created.

Type: Edm.DateTimeOffsetLastUpdatedBy

The ID of the element that updated the annotation.

Type: Edm.StringLastUpdated

The date and time value of the last update of this annotation, with a time zone offset.

Type: Edm.DateTimeOffset

Navigation properties

ApplicationContext

An interface to the collection of configuration information for the annotation.

Type: Collection(tm1.ApplicationContextFacetValue)DimensionalContext

An interface to the collection of dimensions for the annotation.

Type: Collection(tm1.Member)Attachments

Attached documents that provide details and background.

Type: Collection(tm1.Attachment)ContainsTarget: true

ApplicationContextFacetKey: Name

The facet of the application context.

Properties

Name

The name of the application context facet.

Type: Edm.StringNullable: false

Navigation properties

Metadata 25

Values

The value of the application context facet, see ApplicationContextFacetValue.

Type: Collection(tm1.ApplicationContextFacetValue)ContainsTarget: true

ApplicationContextFacetValueKey: Value

A value for a facet of the application context.

Properties

Value

The application context facet value.

Type: Edm.StringNullable: false

Navigation properties

Facet

The description of the application context facet value, see also ApplicationContextFacet.

Type: tm1.ApplicationContextFacetPartner: Values

AttachmentKey: Name

An attached document that provides details and background.

HasStream: true

Properties

Name

The name of the attachment.

Type: Edm.StringNullable: false

Description

A description of the attachment.

Type: Edm.StringContentType

The type of content in the attachment.

Type: Edm.StringSize

The size of the attachment.

Type: Edm.Int64

AttributeDefinitionKey: Name

An interface to describe an attribute.

26 IBM Planning Analytics TM1 REST API

Properties

Name

The name of the attribute.

Type: Edm.StringNullable: false

Type

The type of the attribute.

Type: tm1.AttributeTypeNullable: false

CellsetKey: ID

The result of an execution of a view or an MDX expression.

A cellset represents a snapshot of your data at a certain point in time. You can use the cellset ID within asession instead of running a view or MDX multiple times. Running a view or MDX expression multipletimes can yield different results each time and can have an impact on memory resources. Whenoperations on a cellset have completed, you should delete the cellset if you are not ending the session.When a session ends, the cellset is deleted automatically.

Properties

ID

Read-only property that provides a unique identifier for the cellset for the current session.

The ID does not persist outside of a session because a cellset is transient. You cannot depend on theID being consistent. If you try to access a cellset by using a previous ID value after the session hasended or when the cellset has been deleted, an error is received.

Type: Edm.StringNullable: false

Navigation properties

Cube

The contents of the cellset.

Type: tm1.CubeAxes

A collection of axes for the cellset.

Type: Collection(tm1.CellsetAxis)ContainsTarget: true

Cells

Individual cell value that makes up part of the cellset.

Type: Collection(tm1.CellsetCell)ContainsTarget: true

CellsetAxisKey: Ordinal

Properties

Metadata 27

Ordinal

A number that identifies an entity's position in a series.

Type: Edm.Int32Nullable: false

Cardinality

The cardinality of the cellset axis.

Type: Edm.Int32

Navigation properties

Hierarchies

A collection of hierarchies for this cellset axis.

Type: Collection(tm1.Hierarchy)Tuples

A collection of tuples for this cellset axis.

Type: Collection(tm1.CellsetAxisTuple)ContainsTarget: true

CellsetAxisTupleKey: Ordinal

Properties

Ordinal

A number that identifies an entity's position in a series.

Type: Edm.Int32Nullable: false

Navigation properties

Members

A collection of members that make up this cellset axis.

Type: Collection(tm1.TupleMember)

CellsetCellKey: Ordinal

A cell in a cellset.

Properties

Ordinal

A number that identifies an entity's position in a series.

Type: Edm.Int64Nullable: false

Status

The status of the cell, that is, NULL, DATA, or ERROR.

Type: tm1.CellStatusNullable: false

28 IBM Planning Analytics TM1 REST API

Value

The value of the cell in the cellset.

Type: Edm.PrimitiveTypeFormatString

The format of the cell in the cellset.

Type: Edm.StringFormattedValue

The formatted value of the cell in the cellset.

Type: Edm.StringUpdateable

A value that indicates whether the cell is updateable.

Type: Edm.Int32RuleDerived

A Boolean that indicates whether the cell is rule derived.

Type: Edm.BooleanAnnotated

A Boolean that indicates whether the cell is annotated.

Type: Edm.BooleanConsolidated

A Boolean that indicates whether the cell is consolidated.

Type: Edm.BooleanNullIntersected

Type: Edm.BooleanLanguage

The language of the value of the cell.

Type: Edm.Int32HasPicklist

A Boolean that indicates whether the value of the cell can be selected from a drop-down list.

Type: Edm.BooleanPicklistValues

The collection of available values that can be selected from the drop-down list.

Type: Collection(Edm.String)Nullable: false

HasDrillthrough

A Boolean that indicates whether drill-through scripts are defined on the cell.

Type: Edm.Boolean

Navigation properties

DrillthroughScripts

The collection of drill throughs.

Type: Collection(tm1.Drillthrough)

Metadata 29

Members

A collection of all members that represent the location, the tuple if you will, of this cell in the cube.Using the cellset's Cells property and expending this Members property effectively returns theflattened cellset.

Type: Collection(tm1.Member)

ChoreKey: Name

Objects that execute one or more processes of TM1 at a user-defined frequency.

Properties

Name

The name of the chore.

Type: Edm.StringNullable: false

StartTime

The start time of the chore.

Type: Edm.DateTimeOffsetNullable: false

DSTSensitive

A Boolean that indicates whether the chore start time is sensitive to daily savings time.

Type: Edm.BooleanNullable: false

Active

A Boolean that indicates whether the chore is active.

Type: Edm.BooleanNullable: false

ExecutionMode

The execution mode of the chore, that is, single or multiple commit.

Type: tm1.ChoreExecutionModeNullable: false

Frequency

The frequency of the chore.

Type: Edm.DurationAttributes

The attributes of the chore.

Type: tm1.Attributes

Navigation properties

LocalizedAttributes

Translated string values for properties of the chore.

Type: Collection(tm1.LocalizedAttributes)ContainsTarget: true

30 IBM Planning Analytics TM1 REST API

Tasks

A collection of tasks that make up the chore.

Type: Collection(tm1.ChoreTask)Partner: ChoreContainsTarget: true

ChoreReferenceKey:

A reference to a chore.

BaseType: tm1.Entry

Navigation properties

Chore

The chore that is referenced.

Type: tm1.Chore

ChoreTaskKey: Step

A task to be completed as part of a Chore.

Properties

Step

A step in a task.

Type: Edm.Int64Nullable: false

Parameters

A collection of parameters for the task.

Type: Collection(tm1.ChoreTaskParameter)Nullable: false

Navigation properties

Process

The process completed in the task.

Type: tm1.ProcessChore

The Chore that the task belongs to.

Type: tm1.ChorePartner: Tasks

ConfigurationKey: ServerName

Specifies configuration parameters as defined in the Tm1s.cfg file for an IBM Cognos TM1 server.

For details about all of the parameters, refer to the comments in the Tm1s.cfg file and the OperationsGuide.

Metadata 31

Properties

ServerName

The name of the server.

Type: Edm.StringNullable: false

AdminHost

The location where TM1 Admin Server is running.

Type: Edm.StringProductVersion

The product version of the TM1 server.

Type: Edm.StringPortNumber

The port number of the TM1 server, which is used to distinguish between multiple servers running onthe same computer.

Type: Edm.Int32ClientMessagePortNumber

A secondary port used to accept client messages concerning the progress and ultimate cancellation ofa lengthy operation without tying up thread reserves.

Type: Edm.Int32HTTPPortNumber

The port number on which the TM1 server listens for incoming HTTP(S) requests.

Type: Edm.Int32IntegratedSecurityMode

A Boolean that indicates whether the TM1 server uses integrated security modes.

Type: Edm.BooleanSecurityMode

The user authentication mode to be used by TM1 server.

Type: Edm.StringPrincipalName

The service principal name (SPN) when using Integrated Login with TM1 Web and constraineddelegation.

Type: Edm.StringSecurityPackageName

If you configure the TM1 server to use Integrated Login, the SecurityPackageName parameter definesthe security package that authenticates your user name and password in Microsoft Windows.

Type: Edm.StringClientCAMURIs

A collection of URIs used to authenticate TM1 clients.

Type: Collection(Edm.String)Nullable: false

32 IBM Planning Analytics TM1 REST API

WebCAMURI

The URI used to authenticate TM1 Web clients.

Type: Edm.StringClientPingCAMPassport

Indicates the interval, in seconds, that a client should ping the CAM server to keep their passportalive.

Type: Edm.Int32ServerCAMURI

Specifies the URI for the internal dispatcher that the TM1 server should use to connect to CognosAuthentication Manager (CAM).

Type: Edm.StringAllowSeparateNandCRules

Lets you specify rule expressions for N: and C: levels on separate lines using identical AREAdefinitions.

Type: Edm.BooleanDistributedOutputDir

Defines the directory to which TUnits are written when a Cognos Insight distributed application isdeployed.

Type: Edm.StringDisableSandboxing

A Boolean that indicates whether users have the ability to use sandboxes across the server.

Type: Edm.BooleanJobQueuing

A Boolean that indicates whether the TM1 server should use queues to merge sandboxes.

Type: Edm.BooleanForceReevaluationOfFeedersForFedCellsOnDataChange

When this parameter is set, a feeder statement is forced to be re-evaluated when data changes.

Type: Edm.BooleanDataBaseDirectory

Specifies the data directory from which the server loads cubes, dimensions, and other objects.

Type: Edm.StringUnicodeUpperLowerCase

Instructs the TM1 server to identify and handle Unicode object names, preventing the creation ofidentical Unicode object names that vary only in case.

Type: Edm.Boolean

CubeKey: Name

Represents a single cube on a TM1 server.

Properties

Name

Name of the cube as it is registered on the server.

Metadata 33

Type: Edm.StringNullable: false

Rules

Cube rules expand the standard hierarchical consolidation operations that you may define within adimension.

Type: Edm.StringDrillthroughRules

Rules associating drill-through scripts with regions of cells in the cube.

Drill-through processes can return query results against either cubes or relational tables.

Type: Edm.StringLastSchemaUpdate

Last schema update date of the cube.

Type: Edm.DateTimeOffsetLastDataUpdate

Last data update date of the cube.

Type: Edm.DateTimeOffsetAttributes

Captions and resource attributes of the cube.

Type: tm1.Attributes

Navigation properties

Dimensions

Represents dimensions that perform calculations, control labels, and format data entry.

Type: Collection(tm1.Dimension)Views

Represents a View object on the TM1 Server.

A View is a child object of a Cube. You can retrieve a list of available Views, or find a specific Viewusing the appropriate methods in the Cube class. View objects can be queried for information (such asname or subsets) or changed. Executing a View results in a Cellset object, which can be used to readthe actual cell data.

Type: Collection(tm1.View)Partner: CubeContainsTarget: true

ViewAttributes

Specific attributes for each View object of the cube.

Type: Collection(tm1.AttributeDefinition)ContainsTarget: true

PrivateViews

Private views are accessible only by the user who registered them.

A private registered view is a named object. It persists after the termination of a client session.

Type: Collection(tm1.View)Partner: Cube

34 IBM Planning Analytics TM1 REST API

ContainsTarget: trueAnnotations

Comments that provide additional information about the cube.

Type: Collection(tm1.Annotation)LocalizedAttributes

Translated string values for properties of the cube.

Type: Collection(tm1.LocalizedAttributes)ContainsTarget: true

CubeDrillthroughKey:

A drill through that drills to a view of a cube.

BaseType: tm1.Drillthrough

CubeReferenceKey:

A reference to a cube.

BaseType: tm1.Entry

Navigation properties

Cube

The cube that is referenced.

Type: tm1.Cube

DimensionKey: Name

Represents a single dimension on a TM1 server.

A dimension is a broad grouping of descriptive data about a major aspect of a business, such as products,dates, or locations. Each dimension includes different levels of members in one or more hierarchies andan optional set of calculated members or special categories.

Properties

Name

The name of the dimension.

Type: Edm.StringNullable: false

UniqueName

The caption for the dimension.

Type: Edm.StringAllLeavesHierarchyName

The name of the all leaves hierarchy in a dimension with alternate hierarchies. Defaults to 'Leaves' ifno name is specified.

A dimension with more than one hierarchy automatically gets a, system maintained, all leaveshierarchy. The name of this hierarchy, if no name is specified this hierarchy is called "Leaves", can be

Metadata 35

controlled with this AllLeavesHierarchyName property. Note that the all leaves hierarchy can also beadded by calling the AddAllLeavesHierarchy action, which converts the dimension into a multihierarchy dimension, if not one already, by adding a second, in this case the all leaves, hierarchy.

Type: Edm.StringAttributes

A property of the dimension.

Attributes have a finite domain within the context of the dimension that they belong to. For example, adimension for a customer may have attributes that describe the city, region, and country that thecustomer belongs to.

Type: tm1.Attributes

Navigation properties

Hierarchies

More specific groupings within a dimension.

For example, for the Years dimension, data can be organized into smaller groups, such as Years,Current Month, and All Dates.

Type: Collection(tm1.Hierarchy)Partner: DimensionContainsTarget: true

DefaultHierarchy

The default hierarchy of the dimension.

Type: tm1.HierarchyHierarchyAttributes

Attributes of a hierarchy.

Type: Collection(tm1.AttributeDefinition)ContainsTarget: true

LocalizedAttributes

Translated string values for properties of the dimensions.

Type: Collection(tm1.LocalizedAttributes)ContainsTarget: true

DimensionReferenceKey:

A reference to a dimension.

BaseType: tm1.Entry

Navigation properties

Dimension

The dimension that is referenced.

Type: tm1.Dimension

DocumentKey:

An attached document.

36 IBM Planning Analytics TM1 REST API

BaseType: tm1.Entry

Properties

Size

The size of the document.

Type: Edm.Int64LastUpdated

The date and time value of the last update of this document, with a time zone offset.

Type: Edm.DateTimeOffsetContent

The contents of the document.

Type: Edm.Stream

DocumentReferenceKey:

A reference to a document.

BaseType: tm1.Entry

Navigation properties

Document

The document that is referenced.

Type: tm1.Document

DrillthroughKey: Name

Abstract: true

The definition of a drill through on the current cell.

Properties

Name

The name of the drill through.

Type: Edm.StringNullable: false

EdgeKey: ParentName, ComponentName

Represents the relationship between two or more hierarchies and their weight.

Properties

ParentName

The name of the parent of the component in the hierarchy.

Type: Edm.StringNullable: false

ComponentName

The name of the component in the hierarchy.

Metadata 37

Type: Edm.StringNullable: false

Weight

The weight of the component in the edge.

Type: Edm.Double

Navigation properties

Hierarchy

The hierarchy of the component in the edge.

Type: tm1.HierarchyPartner: Edges

Parent

The parent of the component.

Type: tm1.ElementComponent

The component.

Type: tm1.Element

ElementKey: Name

An element in a dimension that identifies the location of a cell in a cube.

Properties

Name

The name of the element.

Type: Edm.StringNullable: false

UniqueName

The element's invariant name.

Type: Edm.StringType

The type of the element, one of Numeric, String, or Consolidated.

Type: tm1.ElementTypeLevel

The level to which the element belongs within the dimension hierarchy.

Level 0 identifies leaf elements. Each level of consolidation within the dimension hierarchy isincremented by 1.

Type: Edm.Int32Index

A value that corresponds to the position of the element within a dimension.

The first element within a dimension has an index value of 1, the second element has an index valueof 2, and so on.

Type: Edm.Int32

38 IBM Planning Analytics TM1 REST API

Attributes

The attributes of the element.

Type: tm1.Attributes

Navigation properties

Hierarchy

The hierarchy of the element in the dimension.

Type: tm1.HierarchyPartner: Elements

Parents

The parent element of the element in the hierarchy.

Type: Collection(tm1.Element)Components

The collection of elements in the dimension.

Type: Collection(tm1.Element)Edges

The collection of edges in the dimension.

Type: Collection(tm1.Edge)LocalizedAttributes

Translated string values for properties of the element.

Type: Collection(tm1.LocalizedAttributes)ContainsTarget: true

EntryKey: ID

An entry.

Properties

ID

The ID of the entry.

Type: Edm.StringNullable: false

Name

The name of the entry.

Type: Edm.StringNullable: false

Attributes

The attributes of the entry.

Type: tm1.Attributes

Navigation properties

ContainedBy

The folder that contains the entries.

Metadata 39

Type: tm1.FolderLocalizedAttributes

Translated string values for properties of the entry.

Type: Collection(tm1.LocalizedAttributes)ContainsTarget: true

ErrorLogFileKey: Filename

An error log file

Properties

Filename

The name of the error log file.

Type: Edm.StringNullable: false

Content

The content of the process error.

Type: Edm.Stream

FolderKey:

A container for related TM1 objects.

BaseType: tm1.Entry

Navigation properties

Contents

A collection of entries that are in the folder.

Type: Collection(tm1.Entry)ContainsTarget: true

PrivateContents

A collection of private entries that are in the folder.

Type: Collection(tm1.Entry)ContainsTarget: true

GroupKey: Name

A user group on a TM1 server.

Properties

Name

The name of a user group on the TM1 server.

There are three predefined groups on each server: Admin, DataAdmin, and SecurityAdmin. Other usergroups can be created by an administrator as required.

Type: Edm.String

40 IBM Planning Analytics TM1 REST API

Nullable: false

Navigation properties

Users

The names of users in a given group.

Type: Collection(tm1.User)Partner: Groups

HierarchyKey: Name

A hierarchy organizes dimensions into a hierarchical structure, with each dimension representing adifferent level of the hierarchy.

For example, you have separate dimensions for days, months, and quarters. You group them into adimension called year.

Properties

Name

The name of the hierarchy.

Type: Edm.StringNullable: false

UniqueName

The caption of the hierarchy.

Type: Edm.StringCardinality

The cardinality of a relationship is the number of related rows for each of the two query subjects.

Relationships exist between two query subjects. The cardinality of a relationship is the number ofrelated rows for each of the two query subjects. The rows are related by the expression of therelationship. This expression usually refers to the primary and foreign keys of the underlying tables.

Type: Edm.Int32Structure

Specifies whether the hierarchy is balanced or unbalanced.

A value of 0 indicates a balanced structure and a value of 2 indicates an unbalanced structure.

Type: Edm.Int32Visible

Indicates if this hierarchy should be visible to consumers.

A designer of a dimension might opt to use additional hierarchies for modeling purposes and expresshis or her preference to not make such hierarchy 'visible' using this property. A consumer however isfree to ignore this flag, like modeling clients would obviously, if such behavior would be moreappropriate. Note: this flag has absolutely no meaning to the server!

Type: Edm.BooleanAttributes

The attributes of the hierarchy.

Type: tm1.Attributes

Navigation properties

Metadata 41

Dimension

A dimension that is part of the hierarchy.

Type: tm1.DimensionPartner: Hierarchies

Elements

The elements of the hierarchy.

Type: Collection(tm1.Element)Partner: HierarchyContainsTarget: true

Edges

The edges of the hierarchy.

Type: Collection(tm1.Edge)Partner: HierarchyContainsTarget: true

Subsets

The subsets of the hierarchy.

Type: Collection(tm1.Subset)Partner: HierarchyContainsTarget: true

PrivateSubsets

The private subsets of the hierarchy.

Type: Collection(tm1.Subset)Partner: HierarchyContainsTarget: true

SessionSubsets

The session-scoped subsets generated on this hierarchy.

This collection will always appear empty, like the Cellsets collection, but generated SessionSubsetscan be retrieved directly by ID.

Type: Collection(tm1.Subset)Partner: HierarchyContainsTarget: true

Members

The members of the hierarchy.

Type: Collection(tm1.Member)Partner: HierarchyContainsTarget: true

AllMember

An aggregation of all of the members of the hierarchy.

Type: tm1.MemberPartner: Hierarchy

42 IBM Planning Analytics TM1 REST API

DefaultMember

The default member of the hierarchy.

Type: tm1.MemberPartner: Hierarchy

Levels

A collection of levels in the hierarchy.

Type: Collection(tm1.Level)Partner: HierarchyContainsTarget: true

LocalizedAttributes

Translated string values for properties of the hierarchy.

Type: Collection(tm1.LocalizedAttributes)ContainsTarget: true

ElementAttributes

The attributes of the elements of the hierarchy.

Type: Collection(tm1.AttributeDefinition)ContainsTarget: true

SubsetAttributes

The attributes of the subsets of the hierarchy.

Type: Collection(tm1.AttributeDefinition)ContainsTarget: true

LevelKey: Number

A level in the hierarchy of a set of cubes.

Properties

Number

The level number.

Type: Edm.Int32Nullable: false

Name

The name of the level.

Type: Edm.StringNullable: false

UniqueName

The unique name of the level.

Type: Edm.StringCardinality

The cardinality of the level, that is, the number of elements in the level.

Type: Edm.Int32

Metadata 43

Type

The type of the level.

Type: Edm.Int32

Navigation properties

Hierarchy

The hierarchy of the level.

Type: tm1.HierarchyPartner: Levels

Members

The members of the level.

Type: Collection(tm1.Member)Partner: Level

LinkKey:

A link to another website or resource.

BaseType: tm1.Entry

Properties

URL

The URL of the link.

Type: Edm.StringNullable: false

LocalizedAttributesKey: LocaleID

A combination of international language codes defined by ISO 639-1 to identify major languages and IETFlanguage tags to identify specific locales.

For example, "fr" identifies French and "fr-CA" identifies Canadian French.

Properties

LocaleID

The ID of the locale. To use the default locale, specify 'Default'.

Type: Edm.StringNullable: false

Attributes

A set of attributes for the locale.

Type: tm1.Attributes

LoggerKey: Name

A logger to be configured for a TM1 server.

Properties

44 IBM Planning Analytics TM1 REST API

Name

The name of the logger.

Type: Edm.StringNullable: false

Level

The level of the logger, that is, Fatal, Error, Warning, Info, Debug, Unknown, or Off.

Type: tm1.LogLevelNullable: false

MDXViewKey:

OpenType: true

A view of a cube that is defined by an MDX expression.

BaseType: tm1.View

Properties

MDX

An MDX expression that defines a cube view.

Type: Edm.StringNullable: false

MemberKey: Name

A set of elements that are members of the consolidation.

Properties

Name

The name of the member.

Type: Edm.StringNullable: false

UniqueName

The name of the member, preceded by the name of the parent, for example, [dimension_name]:[member_name].

Type: Edm.StringType

The type of the member.

Type: tm1.MemberTypeOrdinal

A number that identifies an entity's position in a series.

Type: Edm.Int32IsPlaceholder

A Boolean that indicates whether this member is a placeholder.

Type: Edm.Boolean

Metadata 45

Weight

The weight of the member within a consolidation.

Weight is a factor applied to an individual member when summing the members of a consolidation.

Type: Edm.DoubleAttributes

The attributes of the member.

Type: tm1.Attributes

Navigation properties

Hierarchy

The hierarchy of the member.

Type: tm1.HierarchyPartner: Members

Level

The level within the hierarchy on which this member resides.

Type: tm1.LevelPartner: Members

Element

The member element.

Type: tm1.ElementParent

The parent of the member in the consolidation.

Type: tm1.MemberPartner: Children

Children

The children of the member in the consolidation.

Type: Collection(tm1.Member)Partner: Parent

LocalizedAttributes

Translated string values for properties of the member.

Type: Collection(tm1.LocalizedAttributes)ContainsTarget: true

MessageLogEntryKey: ID

An entry in the message log.

The message log displays status messages on the activity of the TM1 server in a log file. These messagescontain details on activity such as executed processes, chores, loaded cubes and dimensions, andsynchronized replication.

Properties

ID

The ID of the message log entry.

46 IBM Planning Analytics TM1 REST API

Type: Edm.Int64Nullable: false

ThreadID

The thread ID of the message log entry.

Type: Edm.Int64SessionID

The session ID of the message log entry.

Type: Edm.Int64Level

The level of the message log entry, that is, Fatal, Error, Warning, Info, Debug, Unknown, Off.

Type: tm1.LogLevelNullable: false

TimeStamp

The date and time of the message log entry.

Type: Edm.DateTimeOffsetLogger

The logger of the message log entry.

Type: Edm.StringNullable: false

Message

The message in the message log entry.

Type: Edm.StringNullable: false

NativeViewKey:

OpenType: true

A native view of a cube.

BaseType: tm1.View

Properties

Columns

The dimension elements that exist on the column axis of a view.

Type: Collection(tm1.ViewAxisSelection)Nullable: false

Rows

The dimension elements that exist on the row axis of a view.

Type: Collection(tm1.ViewAxisSelection)Nullable: false

Titles

The dimension elements that exist as title (context) elements of a view.

Type: Collection(tm1.ViewTitle)

Metadata 47

Nullable: falseSuppressEmptyColumns

A Boolean that suppresses any columns that contain only zero values.

Type: Edm.BooleanSuppressEmptyRows

A Boolean that suppresses any rows that contain only zero values.

Type: Edm.BooleanFormatString

The format of the elements in the view.

Type: Edm.StringNullable: false

ProcessKey: Name

A TurboIntegrator process that can be used to manipulate TM1 data and metadata.

Properties

Name

The name of a TurboIntegrator process.

Type: Edm.StringNullable: false

HasSecurityAccess

A Boolean that indicates whether the user security access to run this process.

Type: Edm.BooleanPrologProcedure

The code that is executed during the Prolog stage of the process.

Type: Edm.StringMetadataProcedure

The code that is executed during the Metadata stage of the process.

Type: Edm.StringDataProcedure

The code that is executed during the Data stage of the process.

Type: Edm.StringEpilogProcedure

The code that is executed during the Epilog stage of the process.

Type: Edm.StringDataSource

The source of the data for the process.

Type: tm1.ProcessDataSourceParameters

Parameters used by the process.

48 IBM Planning Analytics TM1 REST API

Type: Collection(tm1.ProcessParameter)Nullable: false

Variables

Variables used by the process.

Type: Collection(tm1.ProcessVariable)Nullable: false

Attributes

The attributes of the process.

Type: tm1.Attributes

Navigation properties

LocalizedAttributes

Translated string values for properties of the process.

Type: Collection(tm1.LocalizedAttributes)ContainsTarget: true

ErrorLogs

A collection of error logs for the process.

Type: Collection(tm1.ProcessErrorLog)ContainsTarget: true

ProcessDebugContextKey: ID

A debug session of a TurboIntegrator process.

Properties

IDType: Edm.StringNullable: false

Status

The state of the process that is being debugged.

Type: tm1.ProcessDebugContextStatusNullable: false

LastActivityDuration

The number of milliseconds that have elapsed since the last debug action.

Type: Edm.Int64ObjectLocks

A collection of object locks that are held by the TurboIntegrator process under debug.

Type: Collection(tm1.ProcessDebugContextObjectLock)Result

Once the process execution has completed this contains the execution results.

Type: tm1.ProcessExecuteResult

Navigation properties

Metadata 49

CurrentBreakpoint

The breakpoint that the process is currently paused at.

Type: tm1.ProcessDebugContextBreakpointProcess

The TurboIntegrator process passed to the debug action.

Type: tm1.ProcessCallStack

The execution stack that represents the current execution state.

Type: Collection(tm1.ProcessDebugContextStackFrame)ContainsTarget: true

Breakpoints

A list of breakpoints that apply to this debug session.

Type: Collection(tm1.ProcessDebugContextBreakpoint)Partner: ProcessDebugContextContainsTarget: true

Thread

The thread that is executing the process for the debug session.

Type: tm1.Thread

ProcessDebugContextBreakpointKey: ID

Abstract: true

A conditional expression that gets evaluated each time the breakpoint is hit. If the expression evaluates totrue, execution is paused. Otherwise execution continues.

Valid operators are '=', '<>', '@=', '@<>', '<', '<=', '>', '>=', '&', '%', '~', '+', '-', '*', '/', '\', '^', '|'. Parenthesis andvariable names are also supported. Function calls are not allowed. These operators should have the samesemantics when used here as they would if used in a TurboIntegrator script.

Properties

IDType: Edm.Int32Nullable: false

EnabledType: Edm.BooleanNullable: false

HitModeType: tm1.ProcessDebugContextHitModeNullable: false

HitCountType: Edm.Int64

ExpressionType: Edm.String

ProcessDebugContextDataBreakpointKey:

50 IBM Planning Analytics TM1 REST API

A breakpoint that pauses execution when the named variable is written to.

BaseType: tm1.ProcessDebugContextBreakpoint

Properties

VariableNameType: Edm.StringNullable: false

ProcessDebugContextLineBreakpointKey:

A breakpoint that pauses execution at a specific script line.

BaseType: tm1.ProcessDebugContextBreakpoint

Properties

ProcessNameType: Edm.StringNullable: false

ProcedureType: tm1.ProcessProcedureNullable: false

LineNumberType: Edm.Int32Nullable: false

ProcessDebugContextLockBreakpointKey:

A breakpoint that pauses execution when an object lock is acquired.

BaseType: tm1.ProcessDebugContextBreakpoint

Properties

ObjectNameType: Edm.StringNullable: false

ObjectTypeType: Edm.StringNullable: false

LockModeType: tm1.ProcessDebugContextLockModeNullable: false

ProcessDebugContextStackFrameKey: ID

A single frame in the execution stack.

Properties

IDType: Edm.StringNullable: false

Metadata 51

ProcedureType: tm1.ProcessProcedureNullable: false

LineNumberType: Edm.Int32Nullable: false

RecordNumberType: Edm.Int32

Navigation properties

ProcessType: tm1.Process

Variables

The entire list of active variables available to the process.

Type: Collection(tm1.ProcessDebugContextVariable)ContainsTarget: true

ProcessDebugContextVariableKey: Name

Properties

NameType: Edm.StringNullable: false

ValueType: Edm.PrimitiveType

ProcessErrorLogKey: Timestamp

A process error log entry.

Properties

Timestamp

The date and time of the process error.

Type: Edm.DateTimeOffsetNullable: false

Content

The content of the process error.

Type: Edm.Stream

ProcessReferenceKey:

A reference to a process.

BaseType: tm1.Entry

Navigation properties

52 IBM Planning Analytics TM1 REST API

Process

The process that is referenced.

Type: tm1.Process

RelationalDrillthroughKey:

A drill through that drills to an Open Database Connectivity (ODBC) table.

BaseType: tm1.Drillthrough

SQLDataSourceKey: Name

A representation of a SQL (read: ODBC) data source available on the host on which the TM1 server isrunning.

Properties

Name

The name of the SQL data source.

Type: Edm.StringNullable: false

Description

A description of the data source.

Type: Edm.String

SandboxKey: Name

A sandbox that allows you to work with your data without affecting your base.

Sandboxes allow you to work with your data in different versions, allowing you to add or modify it to seethe results without affecting your base. Changes that you make in a sandbox are not made public until youcommit the changes. You can continue to work with your data until you are satisfied with the result.

Properties

Name

The name of a sandbox.

Type: Edm.StringNullable: false

IsLoaded

A Boolean that specifies whether the sandbox is loaded into memory. Read-only.

Type: Edm.BooleanIsActive

A Boolean that indicates whether the current context is an active sandbox.

Used when the !sandbox parameter is used as a query option.

Type: Edm.BooleanIsQueued

A Boolean that indicates whether the current context is queued and therefore read-only.

Metadata 53

Type: Edm.BooleanIncludeInSandboxDimension

A Boolean that indicates whether the sandbox is to be included in the sandbox dimension.

Type: Edm.Boolean

ServerKey: Name

A read-only collection of properties of the running server. Available without authenticating.

Properties

Name

The name of the server.

Type: Edm.StringNullable: false

ProductVersion

The product version of the TM1 server.

Type: Edm.StringPortNumber

The port number of the TM1 server, which is used to distinguish between multiple servers running onthe same computer.

Type: Edm.Int32ClientMessagePortNumber

A secondary port used to accept client messages concerning the progress and ultimate cancellation ofa lengthy operation without tying up thread reserves.

Type: Edm.Int32HTTPPortNumber

The port number on which the TM1 server listens for incoming HTTP(S) requests.

Type: Edm.Int32UsingSSL

Whether or not the server is configured to use SSL for client connections.

Type: Edm.BooleanSecurityPackageName

If you configure the TM1 server to use Integrated Login, the SecurityPackageName parameter definesthe security package that authenticates your user name and password in Microsoft Windows.

Type: Edm.StringServicePrincipalName

The service principal name (SPN) when using Integrated Login with TM1 Web and constraineddelegation.

Type: Edm.StringIntegratedSecurityMode

The authentication scheme supported by TM1 Server.

Type: tm1.SecurityMode

54 IBM Planning Analytics TM1 REST API

ClientCAMURI

The URI clients use to connect to the CAM provider to retrieve a CAM passport.

Type: Edm.StringClientPingCAMPassport

Indicates the interval, in seconds, that a client should ping the CAM server to keep their passportalive.

Type: Edm.Int32

ServerSettingsKey: ServerName

The settings for a TM1 server.

Properties

ServerName

The name of the TM1 server.

Type: Edm.StringNullable: false

Access

The access settings of the TM1 server, that is, network, authentication, SSL, CAM, LDAP, CAPI, andHTTP settings.

Type: tm1.AccessSettingsAdministration

The administration settings, including client, audit log, debug log, server log, Java, external database,and TM1 Web settings.

Type: tm1.AdministrationSettingsModelling

The modelling settings of the TM1 server.

Type: tm1.ModellingSettingsPerformance

The performance settings of the TM1 server.

Type: tm1.PerformanceSettings

SessionKey: ID

Represents a unique user session with the server.

Properties

ID

The ID uniquely identifying the session.

Type: Edm.Int64Context

The Context specified by the client to help identifying the consumer of this session.

Type: Edm.String

Metadata 55

Navigation properties

User

The user that is associated to this session.

Type: tm1.UserPartner: Sessions

Threads

The names of users in a given group.

Type: Collection(tm1.Thread)Partner: Session

SubsetKey: Name

Properties

Name

The name of the subset.

Type: Edm.StringNullable: false

UniqueName

The name of the subset, preceded by the parent dimension and separated by a colon, for example,[dimension_name]:[subset_name].

Type: Edm.StringExpression

An MDX expression that defines the subset.

Type: Edm.StringAttributes

The attributes of the subset.

Type: tm1.Attributes

Navigation properties

Hierarchy

The hierarchies that are included in the subset.

Type: tm1.HierarchyPartner: Subsets

Elements

The elements that are included in the subset.

Type: Collection(tm1.Element)LocalizedAttributes

Translated string values for properties of the subset.

Type: Collection(tm1.LocalizedAttributes)ContainsTarget: true

56 IBM Planning Analytics TM1 REST API

SubsetReferenceKey:

A reference to a subset.

BaseType: tm1.Entry

Navigation properties

Subset

The subset that is referenced.

Type: tm1.Subset

ThreadKey: ID

A thread that can run queries concurrently on the TM1 server.

Properties

ID

Type: Edm.Int64Nullable: false

Type

The type of thread, that is, user, worker, chore, system.

Type: tm1.ThreadTypeNullable: false

Name

The name of the thread.

Type: Edm.StringNullable: false

Context

The context of the thread.

Type: Edm.StringNullable: false

State

The state of the thread.

Type: Edm.StringNullable: false

Function

The function of the thread.

Type: Edm.StringNullable: false

ObjectType

The object type of the thread.

Type: Edm.StringNullable: false

Metadata 57

ObjectName

The name of the object that the thread acts on.

Type: Edm.StringNullable: false

RLocks

A shared lock that allows many threads to read from an object at the same time, but does not allowanother thread to modify or write to this object until all R-locks have been released.

Type: Edm.Int32IXLocks

A lock that reserves the right for a thread to obtain a W-lock on an object when all R-locks have beenreleased.

Type: Edm.Int32WLocks

An exclusive lock that allows only one thread at a time to access and write changes to an object.

Type: Edm.Int32ElapsedTime

The elapsed time of a thread in seconds.

Type: Edm.DurationWaitTime

The wait time (delay) before a thread should start the process.

Type: Edm.DurationInfo

The info of the thread.

Type: Edm.StringNullable: false

Navigation properties

Session

The Session that this thread is currently servicing.

Type: tm1.SessionPartner: Threads

TransactionLogEntryKey: ID

An entry in the transaction log.

The transaction log displays the transactions recorded in the Tm1s.log file when a TM1 client changes acube value.

Properties

ID

The ID of the transaction log entry.

Type: Edm.Int64Nullable: false

58 IBM Planning Analytics TM1 REST API

ChangeSetID

The ID of the changeset in the transaction log entry.

Type: Edm.StringTimeStamp

The date and time of the transaction log entry.

Type: Edm.DateTimeOffsetReplicationTime

The replication time of the TM1 server for the transaction log entry.

Type: Edm.DateTimeOffsetUser

The user who completed the changeset in the transaction.

Type: Edm.StringCube

The cube that was acted on in the transaction.

Type: Edm.StringTuple

A collection of tuples that were acted on in the transaction.

Type: Collection(Edm.String)Nullable: false

OldValue

The previous value of the changed tuple in the transaction.

Type: Edm.PrimitiveTypeNewValue

The new value of the changed tuple in the transaction.

Type: Edm.PrimitiveTypeStatusMessage

The status message of the transaction.

Type: Edm.String

TupleMemberKey:

Represents a member in a tuple on an axis in a query result.

BaseType: tm1.Member

Properties

DisplayInfo

This property contains various items of information that help an application render the axis.

The DisplayInfo property contains various items of information that help an application render theaxis. It is a 4-byte value. The value of the least-significant byte of the least significant word containsthe so called drill level. The drill level effectively represents the number of ancestors of a member thatpreceded the member, hence those ancestors being drilled down, without breaking ancestry. Themost significant byte of the least significant word represents the level in the ancestry relative to theancestor at the root of the tree. In the most-significant 2 bytes, each bit potentially conveys one piece

Metadata 59

of display information, however for only 3 bits (the least-significant bits) a meaning has been defined.The least-significant bit (rightmost bit), if set, indicates that this member is drilled down. That is, atleast one descendant of this member appears on the axis, immediately following all occurrences ofthat member. The next bit (the second least-significant bit), if set, indicates that the parent of thismember is the same as the parent of the member preceding all occurrences of the current member.The last bit (the third least-significant bit), if set, indicates that, with the exception of members thatappear at/are at the root, at least one sibling of this member appears on the axis following zero ormore descendants of the member.

Type: Edm.Int32Nullable: false

DisplayInfoAbove

This property contains various items of information that help an application render the axis,presuming children are expanded before their parent.

The DisplayInfoAbove property contains various items of information that help an application renderthe axis, looking at the content of the axis in reverse order, useful in cases where children arepresumed to be expanded before their parent/ancestors. It is a 4-byte value. The value of the least-significant byte of the least significant word contains the so called drill level. The drill level effectivelyrepresents the number of ancestors of a member that follow the member, hence those ancestorsbeing drilled down, or rather up in this case, without breaking ancestry. The most significant byte ofthe least significant word represents the level in the ancestry relative to the ancestor at the root of thetree. In the most-significant 2 bytes, each bit potentially conveys one piece of display information,however for only 3 bits (the least-significant bits) a meaning has been defined. The least-significant bit(rightmost bit), if set, indicates that this member is drilled down, or up in this case. That is, at leastone descendant of this member appears on the axis, immediately preceding all occurrences of thatmember. The next bit (the second least-significant bit), if set, indicates that the parent of this memberis the same as the parent of the member following all occurrences of the current member. The last bit(the third least-significant bit), if set, indicates that, with the exception of members that appear at/areat the root, at least one sibling of this member appears on the axis preceding zero or moredescendants of the member.

Type: Edm.Int32Nullable: false

UserKey: Name

A user on a TM1 server.

Properties

Name

The unique name of the user.

Type: Edm.StringNullable: false

FriendlyName

The friendly name, also known as the display name, of the user.

Type: Edm.StringNullable: false

Password

The password for the user.

Type: Edm.String

60 IBM Planning Analytics TM1 REST API

Type

The type of the user.

Type: tm1.UserTypeNullable: false

IsActive

A Boolean that indicates whether the user is currently logged in to the TM1 server.

Type: Edm.BooleanNullable: false

Enabled

A Boolean that indicates whether the user is enabled.

Type: Edm.BooleanNullable: false

Navigation properties

Groups

The defined groups that the user belongs to. A user can belong to multiple groups.

Type: Collection(tm1.Group)Partner: Users

Sessions

The set of currently active sessions of this user.

Type: Collection(tm1.Session)Partner: User

ViewKey: Name

Abstract: true

OpenType: true

A view of data in a cube.

Properties

Name

The name of the view.

Type: Edm.StringNullable: false

Attributes

The attributes of the view.

Type: tm1.Attributes

Navigation properties

Cube

The parent cube of the view.

Type: tm1.CubePartner: Views

Metadata 61

LocalizedAttributes

Translated string values for properties of the view.

Type: Collection(tm1.LocalizedAttributes)ContainsTarget: true

ViewReferenceKey:

A reference to a view.

BaseType: tm1.Entry

Navigation properties

View

The view that is referenced.

Type: tm1.View

Complex typesComplex types are structured types with a list of properties but with no key. Complex types can exist onlyas a property of a containing entity or as a temporary value.

AccessSettingsProperties

NetworkType: tm1.NetworkSettings

AuthenticationType: tm1.AuthenticationSettings

SSLType: tm1.SSLSettings

CAMType: tm1.CAMSettings

LDAPType: tm1.LDAPSettings

CAPIType: tm1.CAPISettings

HTTPType: tm1.HTTPSettings

AdministrationSettingsProperties

ServerNameType: Edm.String

AdminHostType: Edm.String

LanguageType: Edm.String

DataBaseDirectoryType: Edm.String

62 IBM Planning Analytics TM1 REST API

UnicodeUpperLowerCaseType: Edm.Boolean

MaskUserNameInServerToolsType: Edm.Boolean

AllowReadOnlyChoreRescheduleType: Edm.Boolean

DisableSandboxingType: Edm.Boolean

RunningInBackgroundType: Edm.Boolean

StartupChoresType: Collection(Edm.String)Nullable: false

PerformanceMonitorOnType: Edm.Boolean

PerfMonActiveType: Edm.Boolean

EnableSandboxDimensionType: Edm.Boolean

ClientsType: tm1.ClientSettings

AuditLogType: tm1.AuditLogSettings

DebugLogType: tm1.DebugLogSettings

ServerLogType: tm1.ServerLogSettings

EventLogType: tm1.EventLogSettings

JavaType: tm1.JavaSettings

ExternalDatabaseType: tm1.ExternalDatabaseSettings

TM1WebType: tm1.TM1WebSettings

FileRetryType: tm1.FileRetrySettings

DownTimeType: Edm.String

AttributesOpenType: true

Properties

CaptionType: Edm.String

AuditLogSettingsProperties

Metadata 63

EnableType: Edm.Boolean

UpdateIntervalType: Edm.Duration

MaxFileSizeKilobytesType: Edm.Int64

MaxQueryMemoryKilobytesType: Edm.Int64

AuthenticationSettingsProperties

SecurityPackageNameType: Edm.String

ServicePrincipalNameType: Edm.String

IntegratedSecurityModeType: tm1.SecurityMode

MaximumLoginAttemptsType: Edm.Int32

CAMSettingsProperties

CAMUseSSLType: Edm.Boolean

ClientURIType: Edm.String

ServerURIsType: Collection(Edm.String)Nullable: false

PortalVariableFileType: Edm.String

ClientPingCAMPassportType: Edm.Int32

ServerCAMURIRetryAttemptsType: Edm.Int32

CreateNewCAMClientsType: Edm.Boolean

CAPISettingsProperties

PortType: Edm.Int32

ClientMessagePortType: Edm.Int32

MessageCompressionType: Edm.Boolean

ProgressMessageType: Edm.Boolean

64 IBM Planning Analytics TM1 REST API

ClientVersionMaximumType: Edm.Int32

ClientVersionMinimumType: Edm.Int32

ClientVersionPrecisionType: Edm.Int32

CalculationComponentProperties

Type

The type of calculation (consolidation or rule-driven) that populates this cell.

Type: tm1.CalculationTypeValue

The value of this cell.

Type: Edm.PrimitiveTypeStatements

The rule statement that populates this cell.

Type: Collection(Edm.String)Components

The set of components that determine the value of this cell.

Type: Collection(tm1.CalculationComponent)

Properties

Cube

Cube containing the cell that is a component of the calculation.

Type: tm1.CubeTuple

Coordinates of the cell that is a component of the calculation.

Type: Collection(tm1.Element)

CellDescriptorProperties

TupleType: Collection(tm1.Element)

CellsetUpdateContains the information necessary to perform a spread to a single cell.

The spreading command indicated by Value is applied to the cell specified by Tuple. Optionally, areference cube and cell can also be specified.

Properties

OrdinalType: Edm.Int64Nullable: false

Metadata 65

ValueType: Edm.StringNullable: false

Properties

ReferenceCubeType: tm1.Cube

ReferenceCellType: Collection(tm1.Element)

ChoreTaskParameterProperties

NameType: Edm.StringNullable: false

ValueType: Edm.PrimitiveType

ClientSettingsProperties

PasswordMinimumLengthType: Edm.Int32

ClientPropertiesSyncIntervalType: Edm.Duration

RetainNonCAMGroupMembershipType: Edm.Boolean

CubeUpdateContains the information necessary to perform a spread to a single cell.

The spreading command indicated by Value is applied to the cell specified by Tuple. Optionally, areference cube and cell can also be specified.

Properties

ValueType: Edm.StringNullable: false

Properties

TupleType: Collection(tm1.Element)

ReferenceCubeType: tm1.Cube

ReferenceCellType: Collection(tm1.Element)

DebugLogSettingsProperties

LoggingDirectoryType: Edm.String

66 IBM Planning Analytics TM1 REST API

DrillthroughRow

EventLogSettingsProperties

EnableType: Edm.Boolean

ScanFrequencyType: Edm.Duration

ThresholdForThreadRunningTimeType: Edm.Duration

ThresholdForThreadWaitingTimeType: Edm.Duration

ThresholdForThreadBlockingNumberType: Edm.Int32

ThresholdForPooledMemoryInMBType: Edm.Int32

ExternalDatabaseSettingsProperties

OracleErrorForceRowStatusType: tm1.OracleErrorForceRowStatus

SQLFetchTypeType: tm1.SQLFetchType

SQLRowsetSizeType: Edm.Int32

ODBCLibraryPathType: Edm.String

TM1ConnectorforSAPType: Edm.Boolean

UseNewConnectorforSAPType: Edm.Boolean

ODBCTimeoutInSecondsType: Edm.Int32

FedCellDescriptorProperties

Fed

Whether or not the cell is fed.

Type: Edm.Boolean

Properties

Cube

Cube containing the cell.

Type: tm1.CubeTuple

Coordinates of the cell.

Metadata 67

Type: Collection(tm1.Element)

FeederTraceProperties

FedCells

Collection of cells that are fed by the source cell.

Type: Collection(tm1.FedCellDescriptor)Statements

Collection of feeder statements that have the source cell on the left hand side.

Type: Collection(Edm.String)

FileRetrySettingsProperties

FileRetryCountType: Edm.Int32

FileRetryDelayMillisecondsType: Edm.Int32

FileRetryFileSpecType: Collection(Edm.String)

HTTPSettingsProperties

PortType: Edm.Int32

SessionTimeoutType: Edm.Duration

JavaSettingsProperties

ClassPathType: Edm.String

JVMPathType: Edm.String

JVMArgsType: Edm.String

JobQueuingSettingsProperties

EnableType: Edm.Boolean

ThreadSleepTimeType: Edm.Duration

ThreadPoolSizeType: Edm.Int32

MaxWaitTimeType: Edm.Duration

68 IBM Planning Analytics TM1 REST API

LDAPSettingsProperties

EnableType: Edm.Boolean

HostType: Edm.String

PortType: Edm.Int32

UseServerAccountType: Edm.Boolean

VerifyCertServerNameType: Collection(Edm.String)Nullable: false

VerifyServerSSLCertType: Edm.Boolean

SkipSSLCertVerificationType: Edm.Boolean

SkipSSLCRLVerificationType: Edm.Boolean

WellKnownUserNameType: Edm.String

PasswordFileType: Edm.String

PasswordKeyFileType: Edm.String

SearchBaseType: Edm.String

SearchFieldType: Edm.String

LockingSettingsProperties

SubsetElementLockBreathingType: Edm.Boolean

UseLocalCopiesForPublicDynamicSubsetsType: Edm.Boolean

PullInvalidationSubsetsType: Edm.Boolean

MTQSettingsProperties

UseAllThreadsType: Edm.Boolean

NumberOfThreadsToUseType: Edm.Int32

SingleCellConsolidationType: Edm.Boolean

Metadata 69

ImmediateCheckForSplitType: Edm.Boolean

OperationProgressCheckSkipLoopSizeType: Edm.Int64

MTFeedersType: Edm.Boolean

MTFeedersAtStartupType: Edm.Boolean

MemorySettingsProperties

ApplyMaximumViewSizeToEntireTransactionType: Edm.Boolean

DisableMemoryCacheType: Edm.Boolean

CacheFriendlyMallocType: Edm.Boolean

MaximumViewSizeMBType: Edm.Int64

MaximumUserSandboxSizeMBType: Edm.Int64

MaximumMemoryForSubsetUndoKBType: Edm.Int64

LockPagesInMemoryType: Edm.Boolean

ModellingSettingsProperties

MDXSelectCalculatedMemberInputsType: Edm.Boolean

DefaultMeasuresDimensionType: Edm.Boolean

UserDefinedCalculationsType: Edm.Boolean

EnableNewHierarchyCreationType: Edm.Boolean

SpreadingType: tm1.SpreadingSettings

TIType: tm1.TISettings

RulesType: tm1.RulesSettings

StartupType: tm1.StartupSettings

SynchronizationType: tm1.SynchronizationSettings

NameValuePairProperties

70 IBM Planning Analytics TM1 REST API

NameType: Edm.StringNullable: false

ValueType: Edm.PrimitiveType

NetworkSettingsProperties

IPAddressType: Edm.String

IPVersionType: tm1.IPVersion

NetRecvBlockingWaitLimitType: Edm.Duration

NetRecvMaxClientIOWaitWithinAPIsType: Edm.Duration

IdleConnectionTimeOutType: Edm.Duration

ReceiveProgressResponseTimeoutType: Edm.Duration

PerformanceSettingsProperties

PrivilegeGenerationOptimizationType: Edm.Boolean

MemoryType: tm1.MemorySettings

MTQType: tm1.MTQSettings

LockingType: tm1.LockingSettings

ViewCalculationType: tm1.ViewCalculationSettings

StargateType: tm1.StargateSettings

JobQueuingType: tm1.JobQueuingSettings

ProcessDataSourceOpenType: true

Properties

TypeType: Edm.StringNullable: false

ProcessDebugContextObjectLockProperties

Metadata 71

ObjectNameType: Edm.StringNullable: false

ObjectTypeType: Edm.StringNullable: false

LockModeType: tm1.ProcessDebugContextLockModeNullable: false

ScopeType: tm1.ProcessDebugContextObjectLockScopeNullable: false

ProcessExecuteResultA process execution return value.

Properties

ProcessExecuteStatusCode

The status code return value.

Type: tm1.ProcessExecuteStatusCodeNullable: false

Properties

ErrorLogFile

The error log for the process.

Type: tm1.ErrorLogFile

ProcessParameterProperties

NameType: Edm.StringNullable: false

PromptType: Edm.String

ValueType: Edm.PrimitiveType

TypeType: tm1.ProcessVariableTypeNullable: false

ProcessSyntaxErrorProperties

ProcedureType: tm1.ProcessProcedureNullable: false

LineNumberType: Edm.Int32

72 IBM Planning Analytics TM1 REST API

Nullable: falseMessage

Type: Edm.StringNullable: false

ProcessVariableProperties

NameType: Edm.StringNullable: false

TypeType: tm1.ProcessVariableTypeNullable: false

PositionType: Edm.Int32

StartByteType: Edm.Int32

EndByteType: Edm.Int32

RuleSyntaxErrorProperties

LineNumber

The number of the line containing the error.

Type: Edm.Int32Message

The error message.

Type: Edm.String

RulesSettingsProperties

AllowSeparateNandCRulesType: Edm.Boolean

AutomaticallyAddCubeDependenciesType: Edm.Boolean

RulesOverwriteCellsOnLoadType: Edm.Boolean

ForceReevaluationOfFeedersForFedCellsOnDataChangeType: Edm.Boolean

SSLSettingsProperties

EnableType: Edm.Boolean

ClientExportServerCertificateType: Edm.Boolean

Metadata 73

CertificateIDType: Edm.String

CertificateFileType: Edm.String

PrivateKeyPwdFileType: Edm.String

PwdKeyFileType: Edm.String

CertAuthorityType: Edm.String

CertRevocationFileType: Edm.String

ClientExportServerKeyIDType: Edm.String

KeyFileType: Edm.String

KeyStashFileType: Edm.String

KeyLabelType: Edm.String

TLSCipherListType: Edm.String

FIPSOperationModeType: tm1.FIPSMode

NIST_SP800_131A_MODEType: Edm.Boolean

ServerLogSettingsProperties

EnableType: Edm.Boolean

LogReleaseLineCountType: Edm.Int32

SpreadingSettingsProperties

SpreadingPrecisionType: Edm.Double

ProportionSpreadToZeroCellsType: Edm.Boolean

StargateSettingsProperties

ZeroWeightOptimizationType: Edm.Boolean

AllRuleCalcStargateOptimizationType: Edm.Boolean

UseStargateForRulesType: Edm.Boolean

74 IBM Planning Analytics TM1 REST API

StartupSettingsProperties

PersistentFeedersType: Edm.Boolean

SkipLoadingAliasesType: Edm.Boolean

MaximumCubeLoadThreadsType: Edm.Int32

LoadPrivateSubsetsOnStartupType: Edm.Boolean

SynchronizationSettingsProperties

SyncUnitSizeType: Edm.Int32

MaximumSynchAttemptsType: Edm.Int32

TISettingsProperties

CognosTM1InterfacePathType: Edm.String

UseExcelSerialDateType: Edm.Boolean

MaximumTILockObjectsType: Edm.Int32

EnableTIDebuggingType: Edm.Boolean

TM1WebSettingsProperties

ExcelWebPublishEnabledType: Edm.Boolean

ViewAxisSelectionProperties

SubsetType: tm1.Subset

ViewCalculationSettingsProperties

MagnitudeDifferenceToBeZeroType: Edm.Int32

CheckFeedersMaximumCellsType: Edm.Int64

CalculationThresholdForStorageType: Edm.Int64

Metadata 75

ViewConsolidationOptimizationType: Edm.Boolean

ViewConsolidationOptimizationMethodType: Edm.String

ViewTitleProperties

SubsetType: tm1.Subset

SelectedType: tm1.Element

Enumerated typesEnumerated types are nominal types that represent a series of related values that are known asmembers.

AttributeTypeMembers:

• Numeric : 0• String : 1• Alias : 2

CalculationTypeMembers:

• Simple : 0• Consolidation : 1• Rule : 2

CellStatusMembers:

• Null : 0• Data : 1• Error : 2

ChoreExecutionModeMembers:

• SingleCommit : 0• MultipleCommit : 1

ConflictResolutionMembers:

• UsingSource : 0• UsingTarget : 1• Individually : 2

76 IBM Planning Analytics TM1 REST API

ElementTypeMembers:

• Numeric : 1• String : 2• Consolidated : 3

EncryptionFileTypeMembers:

• Object : 1• TransactionLog : 2• AuditLog : 3

FIPSModeMembers:

• FIPS_MODE : 1• FIPS_APPROVED : 2• FIPS_NONE : 3

IPVersionIsFlags: true

Members:

• IPv4 : 1• IPv6 : 2• Dual : 3

LogLevelMembers:

• Fatal : 0• Error : 1• Warning : 2• Info : 3• Debug : 4• Unknown : 5• Off : 6

MemberTypeMembers:

• Unknown : 0• Regular : 1• All : 2• Measure : 3• Formula : 4

Metadata 77

OracleErrorForceRowStatusMembers:

• AutoDetect : 0• Default : 1• UseSQLULEN : 2

ProcessDebugContextHitModeMembers:

• BreakAlways : 0• BreakEqual : 1• BreakGreaterOrEqual : 2

ProcessDebugContextLockModeIsFlags: true

Members:

• None : 0• Read : 1• ReadOnly : 2• IntenteXclusiveNoCopy : 4• IntenteXclusive : 8• Write : 16• Any : 31

ProcessDebugContextObjectLockScopeMembers:

• Sandbox : 1• Shared : 2• Temporary : 3

A temporary lock scope that indicates a thread private object is not visible to other threads and will notcause contention with other threads.

ProcessDebugContextStatusMembers:

• Unknown : 0• Running : 1• Paused : 2• Complete : 3

ProcessExecuteStatusCodeMembers:

• CompletedSuccessfully : 0• Aborted : 1• HasMinorErrors : 2

78 IBM Planning Analytics TM1 REST API

• QuitCalled : 3• CompletedWithMessages : 4• RollbackCalled : 5

ProcessProcedureMembers:

• Prolog : 572• Metadata : 573• Data : 574• Epilog : 575

ProcessVariableTypeMembers:

• String : 1• Numeric : 2

SQLFetchTypeMembers:

• ExtendedFetch : 1• FetchScroll : 2• Fetch : 3

SecurityModeMembers:

• Basic : 1• Integrated : 2• Mixed : 3• CAM : 4

ThreadTypeMembers:

• User : 0• Worker : 1• Chore : 2• System : 3

UpdateOrderMembers:

• NoOrder : 0• ByLevel : 1

UserTypeIsFlags: true

Members:

Metadata 79

• User : 0• SecurityAdmin : 1• DataAdmin : 2• Admin : 3• OperationsAdmin : 4

ViewConsolidationOptimizationMethodMembers:

• Tree : 0• Array : 1

FunctionsFunctions in an entity model can have zero or more parameters, and must specify a return type.

ControlCubesReturns only control cubes in the model.

Control cubes are used for "system use" (for example, localized attribute values) to TM1 (identified with'}'). Control cubes don't contain your actual data.

IsBound: false

Returns

Type: Collection(tm1.Cube)

A collection of control cubes.

Nullable: false

ControlDimensionsReturn only control dimensions.

IsBound: false

Returns

Type: Collection(tm1.Dimension)

A collection of control dimensions.

Nullable: false

Cube.DimensionsStorageOrderGets a Cube's Dimensions in current storage order.

IsBound: true

Parameters

Cube

The Cube from which to get the Dimensions in storage order.

Type: tm1.CubeNullable: false

Returns

80 IBM Planning Analytics TM1 REST API

Type: Collection(tm1.Dimension)

The Cube's Dimensions in current storage order..

Nullable: false

GetOIDCKeysReturns OIDC keys. Must be performed by a full admin.

IsBound: false

Returns

Type: Collection(Edm.String)

A collection of OIDC key ids.

Nullable: false

Cellset.GetPartitionRetrieves the cells of a cellset in multiple partitions.

This allows the application to manage processing of the area of the partition based on a defined boundary.

IsBound: true

Parameters

Cellset

The collection of cells.

Type: tm1.CellsetNullable: false

Begin

Defines the cell ordinal of the left or right corner of the closest rectangular area of your cellset.

Type: Edm.Int64End

Defines the cell ordinal of the other edge of the closest rectangular area of your cellset.

Type: Edm.Int64

Returns

Type: Collection(tm1.CellsetCell)

A collection of cellset cells.

Nullable: false

MessageLogReturns a collection of message log entries.

By default, the most recent message log entry is returned first.

IsBound: false

Parameters

Reverse

A Boolean that indicates whether to order message log entries chronologically as they occurred intime.

Metadata 81

Type: Edm.Boolean

Returns

Type: Collection(tm1.MessageLogEntry)

A collection of message log entries.

Nullable: false

ModelCubesReturns only non-control cubes in the model.

IsBound: false

Returns

Type: Collection(tm1.Cube)

A collection of non-control cubes.

If you want all of the cubes (including control), you can use /api/vi/Cubes as a resource identifier.

Nullable: false

ModelDimensionsReturns only model dimensions.

IsBound: false

Returns

Type: Collection(tm1.Dimension)

A collection of model dimensions.

Nullable: false

TailMessageLogInitiates change tracking on the message log.

Initiates change tracking on the message log and returns a delta link referencing the end of the messagelog as-is.

IsBound: false

Returns

Type: Edm.String

Delta link referencing the end of the message log.

Nullable: false

TailTransactionLogInitiates change tracking on the transaction log.

Initiates change tracking on the transaction log and returns a delta link referencing the end of thetransaction log as-is.

IsBound: false

Returns

82 IBM Planning Analytics TM1 REST API

Type: Edm.String

Delta link referencing the end of the transaction log.

Nullable: false

TransactionLogReturns a collection of transaction log entries.

By default, the most recent transaction log entry is returned first.

IsBound: false

Parameters

Reverse

A Boolean that indicates whether to order transaction log entries chronologically as they occurred intime.

Type: Edm.BooleanIgnoreStatusMessages

A Boolean that indicates whether to include or not include status messages in the translation log.

Type: Edm.Boolean

Returns

Type: Collection(tm1.TransactionLogEntry)

A collection of transaction log entries.

Nullable: false

ActionsActions in an entity model can have zero or more parameters, and might specify a return type.

Chore.ActivateActivates a chore.

IsBound: true

Parameters

Chore

The chore to activate.

Type: tm1.ChoreNullable: false

Dimension.AddAllLeavesHierarchyAdds the all leaves hierarchy to a single hierarchy dimension and implicitly converts that dimension into amulti hierarchy dimension.

IsBound: true

Parameters

Dimension

The dimension to convert into a multi hierarchy dimension and add the all leaves hierarchy to.

Metadata 83

Type: tm1.DimensionNullable: false

AllLeavesHierarchyName

The name of the all leaves hierarchy (default='Leaves')

Type: Edm.StringVisible

A Boolean indicating if the visible property of the new all leaves hierarchy should be set to true(default=false).

Type: Edm.Boolean

Returns

Type: tm1.Hierarchy

The newly created all leaves hierarchy.

Nullable: false

BeginChangeSetBegins a change set.

IsBound: false

Returns

Type: Edm.String

The ID of the change set that has begun.

Nullable: false

Thread.CancelOperationCancels an operation.

IsBound: true

Parameters

Thread

The thread where the action should be canceled.

Type: tm1.ThreadNullable: false

Cube.CheckFeedersReturns a list of components of a consolidation that are not properly fed.

IsBound: true

Parameters

Cube

Cube containing the cell that should be checked.

Type: tm1.CubeNullable: false

Tuple

Coordinates of the cell that should be checked.

84 IBM Planning Analytics TM1 REST API

Type: Collection(tm1.Element)

Returns

Type: Collection(tm1.FedCellDescriptor)

The collection of improperly fed components of the consolidation.

Nullable: false

Cube.CheckRulesChecks the Cube rules for errors.

IsBound: true

Parameters

Cube

The Cube containing the rules to be checked.

Type: tm1.CubeNullable: false

Returns

Type: Collection(tm1.RuleSyntaxError)

The set of errors in the rules. If no errors are returned, the rules are correct.

Nullable: false

Session.CloseCloses the session.

IsBound: true

Parameters

Session

The session being closed.

Type: tm1.SessionNullable: false

Process.CompileIsBound: true

Parameters

ProcessType: tm1.ProcessNullable: false

Returns

Type: Collection(tm1.ProcessSyntaxError)

CompileProcessIsBound: false

Parameters

Metadata 85

ProcessType: tm1.ProcessNullable: false

Returns

Type: Collection(tm1.ProcessSyntaxError)

ProcessDebugContext.ContinueContinues execution of a paused process debug context.

IsBound: true

Parameters

Context

The debug context to continue.

Type: tm1.ProcessDebugContextNullable: false

Returns

Type: tm1.ProcessDebugContext

Entry.CopyCopies an Entry.

IsBound: true

Parameters

Entry

The source Entry to be copied.

Type: tm1.EntryTarget

The destination folder. If not specified, the source Entry's parent is used.

Type: tm1.FolderPrivate

Whether the new Entry should be private. If not specified, the existing scope is used. Cannot be true ifthe destination folder is private.

Type: Edm.BooleanName

The name of the new Entry.

Type: Edm.String

Returns

Type: tm1.Entry

The new Entry copy.

Nullable: false

Hierarchy.CreateSessionSubsetCreates a session-scoped subset within the hierarchy.

86 IBM Planning Analytics TM1 REST API

The subset will have a generated name, and will not be listed on any collection. The subsets can belooked up by ID, edited with PATCH, and DELETEd. They may also be used by ID in MDX queries, in placeof the subset name. If a named subset exists with the generated ID, the named subset (public or private)will be used in the query instead. These subsets are not persisted and are automatically destroyed whenthe session expires or is logged out. They cannot be retrieved, modified, or used in an MDX query fromanother session.

IsBound: true

Parameters

Hierarchy

Implicit first parameter (this action is bound to a Hierarchy).

Type: tm1.HierarchyNullable: false

Subset

Optional. Subset to be copied (if value is supplied with an entity reference) or a definition to be used(if a subset definition is given as an object).

If this parameter is omitted, an empty subset is created. In the case of a subset definition, the Namesupplied will be ignored, and an ID will be generated.

Type: tm1.Subset

Returns

Type: tm1.Subset

Newly created session-scoped subset that will be contained by the SessionSubsets collection of thebound hierarchy.

Nullable: false

Chore.DeactivateDeactivates a chore.

IsBound: true

Parameters

Chore

The chore to deactivate.

Type: tm1.ChoreNullable: false

Process.DebugStarts a debug session for a process defined in Turbo Integrator.

IsBound: true

Parameters

Process

The process to start the debug session for.

Type: tm1.ProcessNullable: false

Parameters

Override default values (numeric or string) defined in the model.

Metadata 87

Type: Collection(tm1.NameValuePair)

Returns

Type: tm1.ProcessDebugContext

DecryptDataFileDecrypts a single file. Must be performed by a full admin.

IsBound: false

Parameters

SourcePath

The path to the file to be decrypted.

Type: Edm.StringDestinationPath

The path to the directory where the decrypted file should be stored. If unspecified, the file will bedecrypted and replaced.

Type: Edm.StringFileType

The file type of the source file.

Type: tm1.EncryptionFileType

DecryptDataModelDecrypts the data model. Must be performed by a full admin. Will result in a server shutdown.

IsBound: false

Parameters

TimeUntilShutdown

The time until the server shuts down, rounded up to the minute.

Type: Edm.Duration

DeleteAnnotationArtifactsRemoves all annotation-related control cubes and all things related to annotations for the entire modelincluding context facets, comments, attachments, and so on. Use this action with caution because itcannot be undone.

IsBound: false

Sandbox.DiscardChangesResets the values in the sandbox back to the base.

IsBound: true

Parameters

Sandbox

The sandbox to be reset.

Type: tm1.SandboxNullable: false

88 IBM Planning Analytics TM1 REST API

User.DisconnectDisconnects a user but lets threads that are active continue to run until they are done.

IsBound: true

Parameters

User

The user to disconnect.

Type: tm1.UserNullable: false

EncryptDataFileEncrypts a single file. Must be performed by a full admin.

IsBound: false

Parameters

SourcePath

The path to the file to be encrypted.

Type: Edm.StringDestinationPath

The path to the directory where the encrypted file should be stored. If unspecified, the file will beencrypted and replaced.

Type: Edm.StringFileType

The file type of the source file.

Type: tm1.EncryptionFileType

EncryptDataModelEncrypts the data model. Must be performed by a full admin. Will result in a server shutdown.

IsBound: false

Parameters

TimeUntilShutdown

The time until the server shuts down, rounded up to the minute.

Type: Edm.Duration

EndChangeSetEnds a change set.

IsBound: false

Parameters

ChangeSetID

The ID of the change set to end.

Type: Edm.StringNullable: false

Returns

Metadata 89

Type: Edm.Int64

The return code of the EndChangeSet action.

Nullable: false

MDXView.ExecuteRuns a view against the model.

IsBound: true

Parameters

View

The view to be executed, specified in the resource path of the URL.

Type: tm1.MDXViewNullable: false

Returns

Type: tm1.CellsetNullable: false

NativeView.ExecuteRuns a view against the model.

IsBound: true

Parameters

View

The view to be executed, specified in the resource path of the URL.

Type: tm1.NativeViewNullable: false

Titles

The values of the titles in the title axis that you are slicing the view against.

You must specify all titles, even though you may only want change one.

Type: Collection(tm1.Element)SuppressEmptyColumns

Columns without a value are not returned in the result set.

Type: Edm.BooleanSuppressEmptyRows

Rows without a value are not returned in the result set.

Type: Edm.Boolean

Returns

Type: tm1.CellsetNullable: false

Process.ExecuteRuns a process defined in Turbo Integrator.

IsBound: true

90 IBM Planning Analytics TM1 REST API

Parameters

Process

Specifies the process.

This value is not specified because it is obtained by the first parameter in the resource path specifiedin the URL of a POST operation.

Type: tm1.ProcessNullable: false

Parameters

Override default values (numeric or string) defined in the model.

Type: Collection(tm1.NameValuePair)

CubeDrillthrough.ExecuteDrill into a cell.

IsBound: true

Parameters

Drillthrough

The drill through to use.

Type: tm1.CubeDrillthroughNullable: false

Returns

Type: tm1.CellsetNullable: false

RelationalDrillthrough.ExecuteDrill into a cell.

IsBound: true

Parameters

Drillthrough

The drill through to use.

Type: tm1.RelationalDrillthroughNullable: false

Returns

Type: Collection(tm1.DrillthroughRow)Nullable: false

Chore.ExecuteExecutes a chore.

IsBound: true

Parameters

Chore

The chore to execute.

Metadata 91

Type: tm1.ChoreNullable: false

ExecuteChoreRuns a chore.

IsBound: false

Parameters

Chore

Specifies the chore to be executed.

Type: tm1.ChoreNullable: false

ExecuteCubeDrillthroughDrill to the drillthrough process returned cube view.

IsBound: false

Parameters

DrillthroughProcess

A process that returns a handle of a view.

Type: tm1.ProcessNullable: false

Parameters

Parameters used by the process.

Type: Collection(tm1.ProcessParameter)

Returns

Type: tm1.CellsetNullable: false

ExecuteMDXRuns an MDX expression at root level.

IsBound: false

Parameters

MDX

A string value that represents your expression. Included in the POST body of the request.

Type: Edm.StringNullable: false

Returns

Type: tm1.Cellset

A cellset.

Nullable: false

92 IBM Planning Analytics TM1 REST API

ExecuteMDXSetExpressionRuns an MDX set expression at root level.

IsBound: false

Parameters

MDX

A string value that represents your expression. Included in the POST body of the request.

Type: Edm.StringNullable: false

Returns

Type: tm1.CellsetAxis

A cellset axis representing the snapshot of the member set described by the expression

Nullable: false

ExecuteProcessRuns a process defined in Turbo Integrator.

IsBound: false

Parameters

Process

Specifies the process.

This value is not specified because it is obtained by the first parameter in the resource path specifiedin the URL of a POST operation.

Type: tm1.ProcessNullable: false

Parameters

Override default values (numeric or string) defined in the model.

Type: Collection(tm1.NameValuePair)

ExecuteProcessWithReturnRuns a process defined in Turbo Integrator and returns back the status.

IsBound: false

Parameters

Process

Specifies the process.

This value is not specified because it is obtained by the first parameter in the resource path specifiedin the URL of a POST operation.

Type: tm1.ProcessNullable: false

Parameters

Override default values (numeric or string) defined in the model.

Type: Collection(tm1.NameValuePair)

Metadata 93

Returns

Type: tm1.ProcessExecuteResultNullable: false

ExecuteRelationalDrillthroughDrill to relational tables.

IsBound: false

Parameters

DrillthroughProcess

A process that returns a handle of a SQL or CSV table.

Type: tm1.ProcessNullable: false

Parameters

Parameters used by the process.

Type: Collection(tm1.ProcessParameter)

Returns

Type: Collection(tm1.DrillthroughRow)Nullable: false

Process.ExecuteWithReturnRuns a process defined in Turbo Integrator and returns back the status.

IsBound: true

Parameters

Process

Specifies the process.

This value is not specified because it is obtained by the first parameter in the resource path specifiedin the URL of a POST operation.

Type: tm1.ProcessNullable: false

Parameters

Override default values (numeric or string) defined in the model.

Type: Collection(tm1.NameValuePair)

Returns

Type: tm1.ProcessExecuteResultNullable: false

Sandbox.LoadLoads the sandbox into memory on the server.

This action sets the IsLoaded property for Sandbox entity.

IsBound: true

Parameters

94 IBM Planning Analytics TM1 REST API

Sandbox

The sandbox to be loaded.

Type: tm1.SandboxNullable: false

Cube.LockLocks a cube, preventing any users from modifying it until the cube is unlocked.

IsBound: true

Parameters

Cube

The cube to lock.

Type: tm1.Cube

Dimension.LockLocks a dimension, preventing any users from modifying it until the dimension is unlocked.

IsBound: true

Parameters

Dimension

The dimension to lock.

Type: tm1.Dimension

Sandbox.MergeMerges the values of one sandbox with another.

IsBound: true

Parameters

Source

The sandbox to be merged with the target sandbox.

Type: tm1.SandboxNullable: false

Target

The sandbox target that you want to merge to.

Type: tm1.SandboxNullable: false

ConflictResolution

An enumerated value that indicates whether to resolve conflicts using the source, target, orindividually.

Type: tm1.ConflictResolutionAllowQueueing

A Boolean that indicates whether to allow queuing.

Type: Edm.Boolean

Metadata 95

CleanAfter

A Boolean that indicates whether to clean the sandbox after merging.

Type: Edm.Boolean

Entry.MoveMoves an Entry to a new parent folder, renames an Entry, and publishes or privatizes it.

IsBound: true

Parameters

Entry

The Entry to be moved.

Type: tm1.EntryTarget

The destination folder. If not specified, the existing parent is used.

Type: tm1.FolderPrivate

Whether the Entry should be private. If not specified, the existing scope is used. Cannot be true if thedestination folder is private.

Type: Edm.BooleanName

The new name of the Entry.

Type: Edm.String

Returns

Type: tm1.Entry

The moved Entry.

Nullable: false

Sandbox.PublishPublishes the contents (values) of the sandbox back to base.

The sandbox specified is still available for use and is left unchanged.

IsBound: true

Parameters

Sandbox

Specifies the sandbox to publish.

Type: tm1.SandboxNullable: false

ConflictResolution

An enumerated value that indicates whether to resolve conflicts using the source, target, orindividually.

Type: tm1.ConflictResolutionAllowQueueing

A Boolean that indicates whether to allow queuing.

96 IBM Planning Analytics TM1 REST API

Type: Edm.BooleanCleanAfter

A Boolean that indicates whether to clean the sandbox after merging.

Type: Edm.Boolean

RemoveOIDCKeyFromCacheRemoves OIDC key from server cache. Must be performed by a full admin.

IsBound: false

Parameters

KeyId

Optional. The collection of keys to remove. If this parameter is omitted, all keys are removed.

Type: Collection(Edm.String)

Cube.ReorderDimensionsReorders a Cube's Dimensions.

IsBound: true

Parameters

Cube

The Cube that should have its dimensions reordered.

Type: tm1.CubeNullable: false

Dimensions

The new order of Dimensions.

Type: Collection(tm1.Dimension)

Returns

Type: Edm.Double

The percent change in memory usage of the Cube due to the new order.

Nullable: false

RotateDataModelKeyRotates the model key. Must be performed by a full admin.

IsBound: false

Dimension.SaveAsSaves a dimension.

IsBound: true

Parameters

Dimension

The dimension to save.

Type: tm1.DimensionNullable: false

Metadata 97

Name

The name to save the dimension as.

Type: Edm.StringNullable: false

Overwrite

A Boolean that indicates whether to overwrite the dimension that was passed in if it already exists.

Type: Edm.BooleanKeepExistingAttributes

A Boolean that indicates whether overwrite any existing attributes for the dimension, and allcontained objects, we might be replacing with an overwrite. If the save is not overwriting, and thisvalue is set to true, then no attributes will be created for the new dimension.

Type: Edm.Boolean

Returns

Type: tm1.Dimension

The saved dimension.

Nullable: false

Hierarchy.SaveAsSaves a hierarchy.

IsBound: true

Parameters

Hierarchy

The hierarchy to save.

Type: tm1.HierarchyNullable: false

Name

The name to save the hierarchy as.

Type: Edm.StringNullable: false

Overwrite

A Boolean that indicates whether to overwrite the hierarchy that was passed in if it already exists.

Type: Edm.BooleanKeepExistingAttributes

A Boolean that indicates whether overwrite any existing attributes for the hierarchy, and all containedobjects, we might be replacing with an overwrite. If the save is not overwriting, and this value is set totrue, then no attributes will be created for the new hierarchy.

Type: Edm.Boolean

Returns

Type: tm1.Hierarchy

The saved hierarchy.

Nullable: false

98 IBM Planning Analytics TM1 REST API

Subset.SaveAsSaves a subset.

IsBound: true

Parameters

Subset

The subset to save.

Type: tm1.SubsetNullable: false

Name

The name to save the subset as.

Type: Edm.StringNullable: false

MakePrivate

A Boolean that indicates whether to save this subset as private.

Type: Edm.BooleanMakeStatic

A Boolean that indicates whether to save this subset as static.

Type: Edm.Boolean

Returns

Type: tm1.Subset

The saved subset.

Nullable: false

Cellset.SaveViewAsSaves a view.

IsBound: true

Parameters

Cellset

The cellset whose underlying view is to save.

Type: tm1.CellsetNullable: false

Name

The name to save the view as.

Type: Edm.StringNullable: false

Overwrite

A Boolean that indicates whether to overwrite the view that was passed in if it already exists.

Type: Edm.BooleanMakePrivate

A Boolean that indicates whether to save this view as private.

Metadata 99

Type: Edm.Boolean

Returns

Type: tm1.View

The saved view.

Nullable: false

Element.SetComponentSets the child element of a particular element, allowing you to specify the relationship to the parent.

IsBound: true

Parameters

Parent

The parent element to set.

Type: tm1.ElementNullable: false

Element

The element to set as a child of this parent.

Type: tm1.ElementNullable: false

Before

Specifies the position where the new component should be created.

If NULL is specified, the new component is added to the beginning of the set. A POST operationappends to the end of a collection by default.

Type: tm1.ElementWeight

The weight of the element.

Type: Edm.Double

Hierarchy.SetElementInserts an element into a specified position by setting the parent.

IsBound: true

Parameters

Hierarchy

The hierarchy where the element will be inserted.

Type: tm1.HierarchyNullable: false

Element

The element to insert.

Type: tm1.ElementNullable: false

Before

If specified, inserts the element before the element specified.

100 IBM Planning Analytics TM1 REST API

If NULL is specified, the new element is added to the beginning of the set. A POST operation appendsto the end of a collection by default.

Type: tm1.Element

Subset.SetElementInserts an element into a specified subset at a specified location.

IsBound: true

Parameters

Subset

The subset where the element will be inserted.

Type: tm1.SubsetNullable: false

Element

The element to insert.

Type: tm1.ElementNullable: false

Before

If specified, inserts the element before the element specified.

If NULL is specified, the new element is added to the beginning of the set. A POST operation appendsto the end of a collection by default.

Type: tm1.ElementAfter

If specified, inserts the element after the element specified.

If NULL is specified, the new element is added to the end of the set. A POST operation appends to theend of a collection by default.

Type: tm1.Element

Chore.SetServerLocalStartTimeSets the local start time for a server.

IsBound: true

Parameters

Chore

The chore to set the server start time for.

Type: tm1.ChoreNullable: false

StartDate

The start date to set for this chore.

Type: Edm.DateNullable: false

StartTime

The start time to set for this chore.

Type: Edm.TimeOfDay

Metadata 101

Nullable: false

ProcessDebugContext.StepInRuns a single statement from the process.

If that statement is an ExecuteProcess function call, pause at the first statement inside that process.

IsBound: true

Parameters

Context

The debug context.

Type: tm1.ProcessDebugContextNullable: false

Returns

Type: tm1.ProcessDebugContext

ProcessDebugContext.StepOutResumes execution and runs until the current process has finished.

IsBound: true

Parameters

Context

The debug context.

Type: tm1.ProcessDebugContextNullable: false

Returns

Type: tm1.ProcessDebugContext

ProcessDebugContext.StepOverRuns a single statement from the process.

If the statement is an ExecuteProcess function call, do not debug inside the function call.

IsBound: true

Parameters

Context

The debug context.

Type: tm1.ProcessDebugContextNullable: false

Returns

Type: tm1.ProcessDebugContext

Cube.TraceCellCalculationTraces the calculation of a single cell. The result will contain, recursively, any components of thecalculation.

IsBound: true

102 IBM Planning Analytics TM1 REST API

Parameters

Cube

Cube containing the cell that should be traced.

Type: tm1.CubeNullable: false

Tuple

Coordinates of the cell that should be traced.

Type: Collection(tm1.Element)

Returns

Type: tm1.CalculationComponent

Represents the cell that was traced and the components of its calculation.

Nullable: false

Cube.TraceFeedersGet a list of cells that are fed by the specified cell.

IsBound: true

Parameters

Cube

Cube containing the cell that should be traced.

Type: tm1.CubeNullable: false

Tuple

Coordinates of the cell that should be traced.

Type: Collection(tm1.Element)

Returns

Type: tm1.FeederTrace

The feeder statements that use the source cell and the collection of resulting fed cells.

Nullable: false

UndoChangeSetReverts a change set.

Deleting the change set effectively removes all changes made to-date by the session.

IsBound: false

Parameters

ChangeSetID

The ID of the change set to revert.

Type: Edm.StringNullable: false

Metadata 103

Sandbox.UnloadUnloads the sandbox from memory on the server.

This action is useful for freeing up resources when they are no longer needed.

IsBound: true

Parameters

Sandbox

The sandbox to be unloaded.

Type: tm1.SandboxNullable: false

Cube.UnlockUnlocks a cube, allowing modifications.

IsBound: true

Parameters

Cube

The cube to unlock.

Type: tm1.Cube

Dimension.UnlockUnlocks a dimension, allowing modifications.

IsBound: true

Parameters

Dimension

The dimension to unlock.

Type: tm1.Dimension

Cellset.UpdateApplies updates to a cell, or a range of cells, depending on the value of the parameters provided.

IsBound: true

Parameters

Cellset

The cellset targeted by the update, specified in the resource path of the URL.

Type: tm1.CellsetNullable: false

BeginOrdinal

Specifies the cell to update if updating a single cell, or the beginning of the range if updating morethan one cell.

Type: Edm.Int64Nullable: false

EndOrdinal

The last cell position when updating a range of cells.

104 IBM Planning Analytics TM1 REST API

Type: Edm.Int64ReferenceCube

The cube from which the data for the ReferenceCell is sourced.

Type: tm1.CubeReferenceCell

The cell, or slice, containing the source data required by the spreading command.

Type: Collection(tm1.Element)Value

The actual value, typically a spreading command, with which the cell is updated.

Type: Edm.StringNullable: false

Cube.UpdateApplies updates to a cube, a slice of a cube, or cells of a cube, depending on the value of the parametersprovided.

IsBound: true

Parameters

Cube

The cube targeted by the update, specified in the resource path of the URL.

Type: tm1.CubeNullable: false

Slice

The slice of the cube targeted by the update.

Type: Collection(tm1.Element)Cells

The cells of the cube targeted by the update.

Type: Collection(tm1.CellDescriptor)ReferenceCube

The cube containing the source data required by the spreading command.

Type: tm1.CubeReferenceCell

The cell containing the source data required by the spreading command.

Type: Collection(tm1.Element)Value

The actual value, typically a spreading command, with which the cell is updated.

Type: Edm.StringNullable: false

UpdateApplies updates to a cube, a slice of a cube, or cells of a cube, depending on the value of the parametersprovided.

Metadata 105

IsBound: false

Parameters

Cube

The cube targeted by the update, specified in the resource path of the URL.

Type: tm1.CubeNullable: false

Slice

The slice of the cube targeted by the update.

Type: Collection(tm1.Element)Cells

The cells of the cube targeted by the update.

Type: Collection(tm1.CellDescriptor)ReferenceCube

The cube containing the source data required by the spreading command.

Type: tm1.CubeReferenceCell

The cell containing the source data required by the spreading command.

Type: Collection(tm1.Element)Value

The actual value, typically a spreading command, with which the cell is updated.

Type: Edm.StringNullable: false

Cellset.UpdateCellsApplies updates to cells in a cellset.

IsBound: true

Parameters

Cellset

The cellset targeted by the update, specified in the resource path of the URL.

Type: tm1.CellsetNullable: false

Updates

Specifies the cells to update and the values with which to update the cells.

Type: Collection(tm1.CellsetUpdate)Order

The update order to use. Specify 0 for no ordering.

The spreading commands are executed on each cell in the order that they are provided in Updates.Specify 1 to order the cells by level. Leaf cell values are set first and these leaf cells are held. Then,their parents are set and held, and so on, until the highest level consolidations are reached.

Type: tm1.UpdateOrder

106 IBM Planning Analytics TM1 REST API

Cube.UpdateCellsApplies updates to cells of a cube.

IsBound: true

Parameters

Cube

The cube targeted by the update, specified in the resource path of the URL.

Type: tm1.CubeNullable: false

Updates

The cells of the cube targeted by the update and the values with which to update those cells.

Type: Collection(tm1.CubeUpdate)Order

The update order to use. Specify 0 for no ordering.

The spreading commands are executed on each cell in the order that they are provided in Updates.Specify 1 to order the cells by level. Leaf cell values are set first and these leaf cells are held. Then,their parents are set and held, and so on, until the highest level consolidations are reached.

Type: tm1.UpdateOrder

Release notesRelease notes describe the entities, functions, and actions that were introduced for each release of IBMCognos TM1 Server. All changes and additions apply to the current release of Planning Analytics.

What's new in 11.4.0The following functions were introduced in 11.4.0:

• Cube.DimensionsStorageOrder• GetOIDCKeys

The following actions were introduced in 11.4.0:

• Cube.ReorderDimensions• RemoveOIDCKeyFromCache

What's new in 11.3.0The following entity types were introduced in 11.3.0:

• “ErrorLogFile” on page 40

The following entity types were deprecated in 11.3.0:

• ProcessErrorLog

The following complex types were introduced in 11.3.0:

• ProcessExecuteResult

The following enumerated types were introduced in 11.3.0:

• ProcessExecuteStatusCode

The following functions were introduced in 11.3.0:

• TailMessageLog

Metadata 107

• TailTransactionLog

The following actions were introduced in 11.3.0:

• ExecuteProcessWithReturn• Process.ExecuteWithReturn

The following actions were deprecated in 11.3.0:

• Process.Execute• ExecuteProcess

What's new in 11.2.0The following entity types were introduced in 11.2.0:

• SQLDataSource• TupleMember

The following actions were introduced in 11.2.0:

• Entry.Copy• ExecuteCubeDrillthrough• ExecuteRelationalDrillthrough• Entry.Move

What's new in 11.1.0.1The following actions were introduced in 11.1.0.1:

• ExecuteChore

What's new in 11.1.0.0The following complex types were introduced in 11.1.0.0:

• CalculationComponent• EventLogSettings• FedCellDescriptor• FeederTrace• RuleSyntaxError

The following enumerated types were introduced in 11.1.0.0:

• CalculationType

The following actions were introduced in 11.1.0.0:

• Cube.CheckFeeders• Cube.CheckRules• ExecuteMDXSetExpression• Cube.Lock• Dimension.Lock• Cube.TraceCellCalculation• Cube.TraceFeeders• Cube.Unlock• Dimension.Unlock

The following properties were introduced in 11.1.0.0:

108 IBM Planning Analytics TM1 REST API

• Document has new property LastUpdated• ExternalDatabaseSettings has new property ODBCTimeoutInSeconds• Session has new property Context

What's new in 11.0.0.0The following entity types were introduced in 11.0.0.0:

• ProcessDebugContext• ProcessDebugContextBreakpoint• ProcessDebugContextDataBreakpoint• ProcessDebugContextLineBreakpoint• ProcessDebugContextLockBreakpoint• ProcessDebugContextStackFrame• ProcessDebugContextVariable• Server• ServerSettings

The following complex types were introduced in 11.0.0.0:

• AccessSettings• AdministrationSettings• AuditLogSettings• AuthenticationSettings• CAMSettings• CAPISettings• CellsetUpdate• ClientSettings• CubeUpdate• DebugLogSettings• ExternalDatabaseSettings• FileRetrySettings• HTTPSettings• JavaSettings• JobQueuingSettings• LDAPSettings• LockingSettings• MTQSettings• MemorySettings• ModellingSettings• NetworkSettings• PerformanceSettings• ProcessDebugContextObjectLock• ProcessSyntaxError• RulesSettings• SSLSettings• ServerLogSettings

Metadata 109

• SpreadingSettings• StargateSettings• StartupSettings• SynchronizationSettings• TISettings• TM1WebSettings• ViewCalculationSettings

The following enumerated types were introduced in 11.0.0.0:

• FIPSMode• IPVersion• OracleErrorForceRowStatus• ProcessDebugContextHitMode• ProcessDebugContextLockMode• ProcessDebugContextObjectLockScope• ProcessDebugContextStatus• ProcessProcedure• SQLFetchType• SecurityMode• UpdateOrder• ViewConsolidationOptimizationMethod

The following actions were introduced in 11.0.0.0:

• Dimension.AddAllLeavesHierarchy• Process.Compile• CompileProcess• ExecuteProcess• Dimension.SaveAs• Hierarchy.SaveAs• Subset.SaveAs• Cellset.SaveViewAs• Cellset.UpdateCells• Cube.UpdateCells

The following properties were introduced in 11.0.0.0:

• AdministrationSettings has new property EnableSandboxDimension• Dimension has new property AllLeavesHierarchyName• Hierarchy has new property Visible• ModellingSettings has new property EnableNewHierarchyCreation• ProcessParameter has new property Type• Sandbox has new property IncludeInSandboxDimension• User has new property Enabled

The following parameters were introduced in 11.0.0.0:

• Dimension.SaveAs has new parameter KeepExistingAttributes• Hierarchy.SaveAs has new parameter KeepExistingAttributes

110 IBM Planning Analytics TM1 REST API

What's new in 10.2.2.7The following navigation properties were introduced in 10.2.2.7:

• CellsetCell has new navigation property Members

What's new in 10.2.2.6The following entity types were introduced in 10.2.2.6:

• CubeDrillthrough• Drillthrough• Logger• RelationalDrillthrough

The following complex types were introduced in 10.2.2.6:

• DrillthroughRow

The following actions were introduced in 10.2.2.6:

• BeginChangeSet• User.Disconnect• EndChangeSet• CubeDrillthrough.Execute• RelationalDrillthrough.Execute• Subset.SetElement• UndoChangeSet

The following properties were introduced in 10.2.2.6:

• CellsetCell has new property HasDrillthrough• Cube has new property DrillthroughRules

The following navigation properties were introduced in 10.2.2.6:

• CellsetCell has new navigation property DrillthroughScripts

The following enumerated values were introduced in 10.2.2.6:

• LogLevel has new member Off

What's new in 10.2.2.5The following entity types were introduced in 10.2.2.5:

• Session

The following actions were introduced in 10.2.2.5:

• Session.Close

The following properties were introduced in 10.2.2.5:

• Thread has new property ID• User has new property FriendlyName

The following navigation properties were introduced in 10.2.2.5:

• Dimension has new navigation property DefaultHierarchy• Member has new navigation property Level• User has new navigation property Sessions

Metadata 111

What's new in 10.2.2.4The following enumerated types were introduced in 10.2.2.4:

• UserType

The following actions were introduced in 10.2.2.4:

• Update

The following properties were introduced in 10.2.2.4:

• User has new property Type

What's new in 10.2.2.3The following functions were introduced in 10.2.2.3:

• Cellset.GetPartition

What's new in 10.2.2.2The following entity types were introduced in 10.2.2.2:

• ProcessErrorLog

The following actions were introduced in 10.2.2.2:

• Chore.Execute

The following navigation properties were introduced in 10.2.2.2:

• Process has new navigation property ErrorLogs

What's new in 10.2.2.1The following entity types were introduced in 10.2.2.1:

• AttributeDefinition• Chore• ChoreReference• ChoreTask• CubeReference• DimensionReference• Document• DocumentReference• Entry• Folder• Link• MessageLogEntry• ProcessReference• SubsetReference• Thread• TransactionLogEntry• ViewReference

The following complex types were introduced in 10.2.2.1:

• CellDescriptor• ChoreTaskParameter

112 IBM Planning Analytics TM1 REST API

The following enumerated types were introduced in 10.2.2.1:

• AttributeType• ChoreExecutionMode• LogLevel• ThreadType

The following functions were introduced in 10.2.2.1:

• MessageLog• TransactionLog

The following actions were introduced in 10.2.2.1:

• Chore.Activate• Thread.CancelOperation• Chore.Deactivate• ExecuteMDX• Chore.SetServerLocalStartTime• Cube.Update

The following properties were introduced in 10.2.2.1:

• CellsetCell has new property HasPicklist

The following navigation properties were introduced in 10.2.2.1:

• Hierarchy has new navigation property ElementAttributes

What's new in 10.2.2.0The following entity types were introduced in 10.2.2.0:

• Annotation• ApplicationContextFacet• ApplicationContextFacetValue• Attachment• Cellset• CellsetAxis• CellsetAxisTuple• CellsetCell• Configuration• Cube• Dimension• Edge• Element• Group• Hierarchy• Level• LocalizedAttributes• MDXView• Member• NativeView

Metadata 113

• Process• Sandbox• Subset• User• View

The following complex types were introduced in 10.2.2.0:

• Attributes• NameValuePair• ProcessDataSource• ProcessParameter• ProcessVariable• ViewAxisSelection• ViewTitle

The following enumerated types were introduced in 10.2.2.0:

• CellStatus• ConflictResolution• ElementType• MemberType• ProcessVariableType

The following functions were introduced in 10.2.2.0:

• ControlCubes• ControlDimensions• ModelCubes• ModelDimensions

The following actions were introduced in 10.2.2.0:

• DeleteAnnotationArtifacts• Sandbox.DiscardChanges• MDXView.Execute• NativeView.Execute• Process.Execute• Sandbox.Load• Sandbox.Merge• Sandbox.Publish• Element.SetComponent• Hierarchy.SetElement• Sandbox.Unload• Cellset.Update

114 IBM Planning Analytics TM1 REST API

Chapter 5. Representing TM1 dataThe OData standard provides a uniform, commonly accepted method of interacting with data by using aREST interface.

By using OData, API requests and responses are understood regardless of the endpoint that yourapplication communicates with. The TM1 data model is available to consumers through the TM1 RESTAPI as an Entity Data Model (EDM) that conforms to the OData Version 4 protocol.

An EDM is described by using Common Schema Definition Language (CSDL). CSDL uses an XMLrepresentation to describe the TM1 entity data model that is available from the TM1 OData service. To usethe TM1 REST API, you must understand how TM1 data is represented in EDM schema. You must alsounderstand how the “EDM hierarchy” on page 11 is represented.

For example, the View entity is described in the CSDL as an abstract entity. The NativeView andMDXView are based on the View entity. Because the View entity is abstract, it cannot be addresseddirectly, similar to conventions in an object-oriented paradigm.

<EntityType Name="View" Abstract="true" tm1:Plural="Views" tm1:Since="10.2.2.0"> <Key> <PropertyRef Name="Name"/> </Key> <Property Name="Name" Type="Edm.String" Nullable="false"> </Property> <Property Name="Attributes" Type="ibm.tm1.api.v1.Attributes"> </Property> <NavigationProperty Name="LocalizedAttributes" Type="Collection(ibm.tm1.api.v1.LocalizedAttributes)" ContainsTarget="true"> </NavigationProperty> <NavigationProperty Name="Cube" Type="ibm.tm1.api.v1.Cube" Partner="Views"> </NavigationProperty> <tm1:ResourceAttribute Name="view" AttributeType="const weak_ref&lt;View&gt;" ParamType="const weak_ref&lt;View&gt;" ByReference="true" IsPointer="true"/> <tm1:ContainedBy Name="Cube" Type="ibm.tm1.api.v1.Cube" Partner="Views"/> </EntityType>

Discovering an OData serviceA $metadata document, which is available from the TM1 server, returns a CSDL document that describesthe TM1 EDM that is made available by the OData service.

You can examine the $metadata document by executing the following URL:

http://tm1server:8000/api/v1/$metadata

Note: The port number is specified in the HTTPPortNumber entry in the tm1s.cfg file in the modeldirectory.

The CSDL document describes all of the entities and relationships between entities in the data model. Thedefinition for a TM1 cube is shown in the following example:

<EntityType Name="Cube" tm1:Plural="Cubes" tm1:Since="10.2.2.0"> <Key> <PropertyRef Name="Name"/> </Key> <Property Name="Name" Type="Edm.String" Nullable="false"></Property> <Property Name="Rules" Type="Edm.String" Nullable="true"></Property> <Property Name="LastSchemaUpdate" Type="Edm.DateTimeOffset" Nullable="true"></Property> <Property Name="LastDataUpdate" Type="Edm.DateTimeOffset" Nullable="true"></Property> <Property Name="Attributes" Type="ibm.tm1.api.v1.Attributes"></Property> <NavigationProperty Name="Dimensions" Type="Collection(ibm.tm1.api.v1.Dimension)"></NavigationProperty> <NavigationProperty Name="Views" Type="Collection(ibm.tm1.api.v1.View)" Partner="Cube" ContainsTarget="true"></NavigationProperty> <NavigationProperty Name="ViewAttributes" Type="Collection(ibm.tm1.api.v1.AttributeDefinition)" ContainsTarget="true"></

© Copyright IBM Corp. 2007, 2019 115

NavigationProperty> <NavigationProperty Name="PrivateViews" Type="Collection(ibm.tm1.api.v1.View)" Partner="Cube" ContainsTarget="true"></NavigationProperty> <NavigationProperty Name="Annotations" Type="Collection(ibm.tm1.api.v1.Annotation)"></NavigationProperty> <NavigationProperty Name="LocalizedAttributes" Type="Collection(ibm.tm1.api.v1.LocalizedAttributes)" ContainsTarget="true"></NavigationProperty> <NavigationProperty Name="MeasuresDimension" Type="ibm.tm1.api.v1.Dimension" tm1:Hidden="true" tm1:Since="10.2.2.3"></NavigationProperty> <NavigationProperty Name="TimeDimension" Type="ibm.tm1.api.v1.Dimension" tm1:Hidden="true" tm1:Since="10.2.2.3"></NavigationProperty> <tm1:ResourceAttribute Name="cube" AttributeType="Cube" ParamType="const Cube" ByReference="true" IsPointer="false"/> </EntityType>

A representation of a data model in EDM is similar to the object-oriented approach of defined classes andproperties and the relationships between them. For example, in the previous result, a Cube is describedas an entity that contains the properties Name and Rules, which are of type Edm.String. Otherproperties are defined by EDM built-in types or complex types that are specific to the vocabulary. Cubescontain dimensions, which are specified by the Dimensions navigation property, which in turn containhierarchies.

EDM structureThe $metadata for each model describes the structure of the data model according to the conventionsdefined in the OData protocol.

The main components that make up the model are described as follows:

Service DocumentThe context URL of the $metadata of the service. The $metadata document describes the resourcesmade available by the service.

MetadataA conceptual schema definition (CSDL) that describes the EDM, which is exposed as /api/v1/$metadata.

Entity containerA single container in a metadata document that describes the information that is made available bythe service. The entity container represents an entry point into a primary collection of one or moreedm:EntitySet, edm:Singleton, edm:ActionImport, or edm:FunctionImport elements. Forexample, for the TM1 REST API, the edm:EntityContainer element defines the main componentsthat make up the API:

<EntityContainer Name="API"> <EntitySet Name="Cubes" EntityType="ibm.tm1.api.v1.Cube" tm1:Since="10.2.2.0"> <NavigationPropertyBinding Path="Dimensions" Target="Dimensions"/> <NavigationPropertyBinding Path="Annotations" Target="Annotations"/> </EntitySet> <EntitySet Name="Dimensions" EntityType="ibm.tm1.api.v1.Dimension" tm1:Since="10.2.2.0"/> <EntitySet Name="Processes" EntityType="ibm.tm1.api.v1.Process" tm1:Since="10.2.2.0"/> <EntitySet Name="ProcessDebugContexts" EntityType="ibm.tm1.api.v1.ProcessDebugContext" IncludeInServiceDocument="false" tm1:Since="11.0.0.0"> <NavigationPropertyBinding Path="Process" Target="Processes"/> </EntitySet> <EntitySet Name="Annotations" EntityType="ibm.tm1.api.v1.Annotation" tm1:Since="10.2.2.0"/> <EntitySet Name="Cellsets" EntityType="ibm.tm1.api.v1.Cellset" IncludeInServiceDocument="false" tm1:Since="10.2.2.0"> <NavigationPropertyBinding Path="Cube" Target="Cubes"/> </EntitySet> <EntitySet Name="MemberSets" EntityType="ibm.tm1.api.v1.CellsetAxis" IncludeInServiceDocument="false" tm1:Since="11.0.0.2"> <NavigationPropertyBinding Path="Cube" Target="Cubes"/> </EntitySet> <EntitySet Name="Users" EntityType="ibm.tm1.api.v1.User" tm1:Since="10.2.2.0">

116 IBM Planning Analytics TM1 REST API

<NavigationPropertyBinding Path="Groups" Target="Groups"/> <NavigationPropertyBinding Path="Sessions" Target="Sessions"/> </EntitySet> <Singleton Name="ActiveUser" Type="ibm.tm1.api.v1.User" tm1:Since="10.2.2.4"> <NavigationPropertyBinding Path="Groups" Target="Groups"/> <NavigationPropertyBinding Path="Sessions" Target="Sessions"/> </Singleton> <EntitySet Name="Groups" EntityType="ibm.tm1.api.v1.Group" tm1:Since="10.2.2.0"> <NavigationPropertyBinding Path="Users" Target="Users"/> </EntitySet> <EntitySet Name="Sandboxes" EntityType="ibm.tm1.api.v1.Sandbox" tm1:Since="10.2.2.0"/> <EntitySet Name="ApplicationContextFacets" EntityType="ibm.tm1.api.v1.ApplicationContextFacet" tm1:Since="10.2.2.0"/> <EntitySet Name="CubeAttributes" EntityType="ibm.tm1.api.v1.AttributeDefinition" tm1:Since="10.2.2.1"/> <EntitySet Name="DimensionAttributes" EntityType="ibm.tm1.api.v1.AttributeDefinition" tm1:Since="10.2.2.1"/> <EntitySet Name="ProcessAttributes" EntityType="ibm.tm1.api.v1.AttributeDefinition" tm1:Since="11.0.0.0"/> <EntitySet Name="ChoreAttributes" EntityType="ibm.tm1.api.v1.AttributeDefinition" tm1:Since="11.0.0.0"/> <Singleton Name="Configuration" Type="ibm.tm1.api.v1.Configuration" tm1:Since="10.2.2.0"/> <Singleton Name="StaticConfiguration" Type="ibm.tm1.api.v1.ServerSettings" tm1:Since="11.0.0.0"/> <Singleton Name="ActiveConfiguration" Type="ibm.tm1.api.v1.ServerSettings" tm1:Since="11.0.0.0"/> <Singleton Name="Server" Type="ibm.tm1.api.v1.Server" tm1:Since="11.0.0.0"/> <EntitySet Name="Sessions" EntityType="ibm.tm1.api.v1.Session" tm1:Since="10.2.2.5"> <NavigationPropertyBinding Path="User" Target="Users"/> <NavigationPropertyBinding Path="Threads" Target="Threads"/> </EntitySet> <Singleton Name="ActiveSession" Type="ibm.tm1.api.v1.Session" tm1:Since="10.2.2.5"> <NavigationPropertyBinding Path="User" Target="Users"/> <NavigationPropertyBinding Path="Threads" Target="Threads"/> </Singleton> <EntitySet Name="Threads" EntityType="ibm.tm1.api.v1.Thread" tm1:Since="10.2.2.1"> <NavigationPropertyBinding Path="Session" Target="Sessions"/> </EntitySet> <EntitySet Name="Chores" EntityType="ibm.tm1.api.v1.Chore" tm1:Since="10.2.2.1"/> <EntitySet Name="Contents" EntityType="ibm.tm1.api.v1.Folder" tm1:Since="10.2.2.1"/> <EntitySet Name="Loggers" EntityType="ibm.tm1.api.v1.Logger" tm1:Since="10.2.2.6"/> <EntitySet Name="MessageLogEntries" EntityType="ibm.tm1.api.v1.MessageLogEntry" tm1:Since="10.2.2.4"> <Annotation Term="Org.OData.Capabilities.V1.IndexableByKey" Bool="false"/> <Annotation Term="Org.OData.Capabilities.V1.ChangeTracking"> <Record> <PropertyValue Property="Supported" Bool="true"/> <PropertyValue Property="FilterableProperties"> <Collection> <PropertyPath>ThreadID</PropertyPath> <PropertyPath>SessionID</PropertyPath> <PropertyPath>Level</PropertyPath> <PropertyPath>TimeStamp</PropertyPath> <PropertyPath>Logger</PropertyPath> <PropertyPath>Message</PropertyPath> </Collection> </PropertyValue> </Record> </Annotation> </EntitySet> <EntitySet Name="TransactionLogEntries" EntityType="ibm.tm1.api.v1.TransactionLogEntry" tm1:Since="10.2.2.4"> <Annotation Term="Org.OData.Capabilities.V1.IndexableByKey" Bool="false"/> <Annotation Term="Org.OData.Capabilities.V1.ChangeTracking"> <Record> <PropertyValue Property="Supported" Bool="true"/> <PropertyValue Property="FilterableProperties"> <Collection> <PropertyPath>ChangeSetID</PropertyPath> <PropertyPath>TimeStamp</PropertyPath> <PropertyPath>ReplicationTime</PropertyPath> <PropertyPath>Cube</PropertyPath> <PropertyPath>Tuple</PropertyPath> <PropertyPath>OldValue</PropertyPath> <PropertyPath>NewValue</PropertyPath> <PropertyPath>StatusMessage</PropertyPath> </Collection> </PropertyValue> </Record> </Annotation>

Representing TM1 data 117

</EntitySet> <FunctionImport Name="ModelCubes" Function="ibm.tm1.api.v1.ModelCubes" EntitySet="Cubes" IncludeInServiceDocument="true"/> <FunctionImport Name="ControlCubes" Function="ibm.tm1.api.v1.ControlCubes" EntitySet="Cubes" IncludeInServiceDocument="true"/> <FunctionImport Name="ModelDimensions" Function="ibm.tm1.api.v1.ModelDimensions" EntitySet="Dimensions" IncludeInServiceDocument="true"/> <FunctionImport Name="ControlDimensions" Function="ibm.tm1.api.v1.ControlDimensions" EntitySet="Dimensions" IncludeInServiceDocument="true"/> <FunctionImport Name="MessageLog" Function="ibm.tm1.api.v1.MessageLog" IncludeInServiceDocument="true"/> <FunctionImport Name="TransactionLog" Function="ibm.tm1.api.v1.TransactionLog" IncludeInServiceDocument="true"/> <ActionImport Name="ExecuteMDX" Action="ibm.tm1.api.v1.ExecuteMDX" EntitySet="Cellsets"/> <ActionImport Name="ExecuteMDXSetExpression" Action="ibm.tm1.api.v1.ExecuteMDXSetExpression" EntitySet="MemberSets"/> <ActionImport Name="DeleteAnnotationArtifacts" Action="ibm.tm1.api.v1.DeleteAnnotationArtifacts"/> <ActionImport Name="BeginChangeSet" Action="ibm.tm1.api.v1.BeginChangeSet"/> <ActionImport Name="EndChangeSet" Action="ibm.tm1.api.v1.EndChangeSet"/> <ActionImport Name="UndoChangeSet" Action="ibm.tm1.api.v1.UndoChangeSet"/> <ActionImport Name="Update" Action="ibm.tm1.api.v1.Update"/> <ActionImport Name="ExecuteProcess" Action="ibm.tm1.api.v1.ExecuteProcess"/> <ActionImport Name="CompileProcess" Action="ibm.tm1.api.v1.CompileProcess"/> <ActionImport Name="EncryptDataModel" Action="ibm.tm1.api.v1.EncryptDataModel" tm1:hidden="true"/> <ActionImport Name="DecryptDataModel" Action="ibm.tm1.api.v1.DecryptDataModel" tm1:hidden="true"/> <ActionImport Name="EncryptDataFile" Action="ibm.tm1.api.v1.EncryptDataFile" tm1:hidden="true"/> <ActionImport Name="DecryptDataFile" Action="ibm.tm1.api.v1.DecryptDataFile" tm1:hidden="true"/> <ActionImport Name="RotateDataModelKey" Action="ibm.tm1.api.v1.RotateDataModelKey" tm1:hidden="true"/> </EntityContainer>

Entities

An object in the data model and its properties or complex types. An entity is similar to a classdefinition in an object-oriented language. Entities support the following features:

• Named structures with keys• The ability to reference other entities in the model with navigation properties, which define

relationships to other objects• Inheritance from another entity definition

For example, a Cube is made up of dimensions, but the dimensions are not contained within the cube.The entity definition for a Cube references Dimension entities at another location, and identifies theentity type as ibm.tm1.api.v1.Dimension:

<EntityType Name="Cube"> <Key> <PropertyRef Name="Name" /> </Key> <Property Name="Name" Nullable="false" Type="Edm.String" /> <Property Name="Rules" Nullable="true" Type="Edm.String" /> <Property Name="LastSchemaUpdate" Nullable="true" Type="Edm.DateTimeOffset" /> <Property Name="LastDataUpdate" Nullable="true" Type="Edm.DateTimeOffset" /> <Property Name="Attributes" Type="ibm.tm1.api.v1.Attributes" /> <NavigationProperty Name="Dimensions" Type="Collection(ibm.tm1.api.v1.Dimension)" /> <NavigationProperty Name="Views" Type="Collection(ibm.tm1.api.v1.View)" Partner="Cube" ContainsTarget="true" /> <NavigationProperty Name="ViewAttributes" Type="Collection(ibm.tm1.api.v1.AttributeDefinition)" ContainsTarget="true" /> <NavigationProperty Name="PrivateViews" Type="Collection(ibm.tm1.api.v1.View)" Partner="Cube" ContainsTarget="true" /> <NavigationProperty Name="Annotations" Type="Collection(ibm.tm1.api.v1.Annotation)" /> <NavigationProperty Name="LocalizedAttributes" Type="Collection(ibm.tm1.api.v1.LocalizedAttributes)" ContainsTarget="true" /> </EntityType>

The Dimension entity is defined elsewhere in the $metadata document.

118 IBM Planning Analytics TM1 REST API

RelationshipsA relationship can exist between entities in an EDM by:

• Navigation paths that reference another entity or collection of entities in the model. For example, aninvoice entity might have a relationship defined that references a customer ID.

• Containment of one entity by another identified by the ContainesTarget attribute.

The following diagram illustrates the relationship between a Cube and a Dimension entity, and howthe abstract View entity provides the base for the MDXView and NativeView entities.

Cubes and viewsA cube is the basic container for data and a view defines how a cube's dimensions are arranged.

View a cubeYou can use the following GET request to view the Metrics cube-Sales:

GET /api/v1/Cubes('Metrics cube-Sales')

The GET request returns the following Metrics cube-Sales cube:

{ "@odata.context": "$metadata#Cubes/$entity", "Name": "Metrics cube-Sales", "Rules": "#Region System\nFEEDSTRINGS;\nSKIPCHECK;\nUNDEFVALS;\n#EndRegion\n\n#Region ... "LastSchemaUpdate": "2014-05-23T12:45:14.016Z", "LastDataUpdate": "2014-05-23T12:45:14.015Z", "Attributes": { "Caption": "Metrics cube-Sales", "Caption_Default": "Metrics cube-Sales", "CUBE_TYPE": "METRICS" }}

Display the available views in a cubeYou can use the following GET request to display views in the Metrics cube-Sales cube:

GET /api/v1/Cubes('Metrics cube-Sales')/Views?$select=Name

The GET request lists the available views for the Metrics cube-Sales cube:

{ "@odata.context": "../$metadata#Cubes('Metrics%20cube-Sales')/Views(Name)",

Representing TM1 data 119

"value": [ { "@odata.type": "#ibm.tm1.api.v1.NativeView", "Name": "All" }, { "@odata.type": "#ibm.tm1.api.v1.NativeView", "Name": "Metrics cube-Sales" }, { "@odata.type": "#ibm.tm1.api.v1.NativeView", "Name": "View-Sales" } ]}

Get the specification of a viewYou can use the following GET request to see the specification of the Metrics cube-Sales view:

GET /api/v1/Cubes('Metrics cube-Sales')/Views('Metrics cube-Sales')

The result provides the specification of the view. Columns, Rows, and Titles are complex types, which inturn, contain navigation properties. As a result, they are not shown by default:

{ "@odata.context": "../$metadata#Cubes('Metrics%20cube-Sales')/Views/ibm.tm1.api.v1.NativeView/$entity", "@odata.type": "#ibm.tm1.api.v1.NativeView", "Name": "Metrics cube-Sales", "Columns": [ {} ], "Rows": [ {} ], "Titles": [ {}, {}, {}, {} ], "SuppressEmptyColumns": false, "SuppressEmptyRows": false, "FormatString": "0.00"}

Columns, Rows, and Titles are type ViewAxisSelection, that defines a navigation property to theSubset of the dimension.

<ComplexType Name="ViewAxisSelection"> <NavigationProperty Name="Subset" Type="ibm.tm1.api.v1.Subset" /> </ComplexType>

Generally, a cube is displayed as a pivot table, such as the Cube Viewer in TM1 Architect. Suppressbuttons in TM1 Architect correspond to the Suppress properties of a view.

120 IBM Planning Analytics TM1 REST API

Use options to view specific propertiesTo minimize the amount of data that is returned in a result, you can use a $select option to specifywhich properties of the entity to include.

You can use the following GET request to list cube names:

GET Cubes?$select=Name

In the result, only the names of the cubes are returned.

{ "@odata.context": "$metadata#Cubes(Name)", "value": [ { "Name": "plan_BudgetPlan" }, { "Name": "plan_BudgetPlanLineItem" }, { "Name": "plan_Control" }, ... ]}

You can select more than one property to return in the result. For example, if you specifyselect=Name,Dimensions, the GET request returns the following result:

{ "@odata.context": "$metadata#Cubes(Name,Dimensions)", "value": [ { "Name": "plan_BudgetPlan", "Dimensions@odata.navigationLink": "Cubes('plan_BudgetPlan')/Dimensions" }, { "Name": "plan_BudgetPlanLineItem", "Dimensions@odata.navigationLink": "Cubes('plan_BudgetPlanLineItem')/Dimensions" }, ... ]}

In the previous example, the navigation property that provides a link to the dimensions are returnedinstead of the actual dimensions.

List dimensions in a cubeWhen an entity contains navigation properties, a query operation returns only the navigation references tothe contained contents, not the entities themselves.

In the following example, only references to the dimensions that are contained within cubes are returned.The dimensions are not contained in the cube, but are referenced at another location.

GET Cubes('plan_BudgetPlan')/Dimensions

To include the dimensions as part of the payload that is returned, use the $expand query option toinclude them.

GET Cubes?$select=Name&$expand=Dimensions

Representing TM1 data 121

In the previous example, the $select and $expand query options are separated with the ampersandsymbol (&). This request returns the name of the cube and the actual dimension instead of a reference tothe dimension:

{ "@odata.context": "$metadata#Cubes(Name,Dimensions)", "value": [ { "Name": "plan_BudgetPlan", "Dimensions": [ { "Name": "plan_version", "UniqueName": "[plan_version]", "Attributes": { "Caption": "plan_version" } }, ...

Expand dimensions and hierarchies in a cubeYou can expand dimensions and hierarchies in a cube by using the $expand query option.

To recursively expand items in a resource, use the $expand query option. In the following example, thecubes are listed by Name and the dimensions that are contained are listed in addition to the hierarchiescontained within each dimension.

GET /api/v1/Cubes('plan_BudgetPlanLineItem')?$select=Name& $expand=Dimensions($select=Name;$top=2; $expand=Hierarchies($select=Name))

In addition to the $select option, you can use the $top=2 query option to restrict the results to asmaller subset. Separate these options with a semi-colon (";") character. The opening and closingparenthesis contains the scope of the options to the context of the entity that precedes the parenthesis.For example, the last instance of ($select=Name) is contained within open and close parenthesis after$expand=Hierarchies. So this portion of the query, $select=Name;$top=2;$expand=Hierarchies, applies only to Dimensions while $select=Name applies only toHierarchies.

{ "@odata.context": "$metadata#Cubes/$entity", "Name": "plan_BudgetPlanLineItem", "Dimensions": [ { "Name": "plan_version", "Hierarchies": [ { "Name": "plan_version" } ] }, { "Name": "plan_business_unit", "Hierarchies": [ { "Name": "plan_business_unit" } ] } ]}

122 IBM Planning Analytics TM1 REST API

Use the Or operator to specify cube rules across hierarchiesYou can use a single rule statement to cover a set of same-named consolidated elements acrosshierarchies of the same dimension. This approach gives you greater flexibility with alternate hierarchies.

Suppose that your dimension has two hierarchies, H1 and H2, and each hierarchy has a consolidatedelement named US. Previously, a modeler would need to replicate statements to specify a rule calculationfor US, as in the following example:

['Dimension':'H1':'US'] = C:<formula>;['Dimension':'H2':'US'] = C:<formula>;

In the above example, the <formula> are identical. You can now write a single statement that triggers oneither of the US elements by using the extended rule area grammar.

To illustrate, you need to understand how area definitions, AND operators, and OR operators work.

Area definitions

An area definition is an expression in square brackets, comprising the left side of a cube rule statement.For example:

[ 'element' ] = <formula>;

The above statement is eligible for evaluation when a cell retrieval request includes 'element' amongthe cell coordinates. The statement is eligible because the cube's rule file might have other statementsupstream that take precedence. To simplify the concept, remember that if the above were the only rulestatement for this cube, then it's guaranteed that the statement will be evaluated as long as 'element'is among the cell retrieval coordinates.

AND Operator

An area definition can contain a comma-separated list of element references. Such a list represents anAND operator that further restricts the eligibility of the rule statement. For example:

['element', 'measure1' ] = <formula>;

This statement is eligible only if both 'element' AND 'measure1' coincide among the cell retrievalcoordinates. In typical practice, if there were two rule statements, one with area ['element'] and theother with the area ['element', 'measure1'], the latter statement would be placed upstream in therule file. This way, coordinates with ['element'] and any other measure than 'measure1' wouldtrigger evaluation of the ['element'] rule while those that have the 'measure1' in addition would runthe more specific statement. If these statements were in the opposite order, then the ['element','measure1'] statement would never run, it is shadowed by the more general statement above it.

OR Operator

The top-level comma-separated list of terms inside the enclosing [] characters of the area definitionrepresent coordinates that must appear together in the retrieval coordinates to make that rule statementeligible. In the above examples, the terms are simple element references like 'element' and'measure1'. But each term can optionally be list, enclosed in curly braces {}, that represent differentelements from the same dimension. These list terms must be simple element references and theyrepresent alternatives each of which would make the statement eligible if they appear in the retrievalcoordinates. This is an OR operation, as illustrated by this example:

['element', { 'measure1', 'measure2' } ] = <formula>;

The above area definition specifies that if the retrieval coordinates include 'element' from itsdimension, AND ( 'measure1' OR 'measure2' from the measures dimension) then the rule statementis eligible.

Representing TM1 data 123

Dimension and Hierarchy Qualification

Previously, dimension qualification of element references is recommended, though it is also optional.Dimension qualification of an example above would look like this:

[ 'Products':'element', 'Measures':{ 'measure1', 'measure2' } ] = <formula>;

The terms in the AND list must be from different dimensions of the cube, while the terms in the OR listmust be from the same dimension.

Hierarchy qualification is now recommended, for example:

[ 'Products':'H2':'element', 'Flavors':'H1':{ 'flavor1', 'flavor2' } ] = <formula>;

However, the OR operator {} is limited to elements within the same hierarchy. It should be more generalthan this, since elements from different hierarchies of the same dimension, are still elements from thesame dimension.

You can now take advantage of more flexible use of the OR operator in rule area definitions.

Examples

The following examples illustrate the various permitted forms of the OR {} operator.

The following examples show an unqualified OR list, and a dimension qualified OR list. In all cases, theelements in the list must resolve to being from the same dimension.

{ 'e1', 'e2' }'d':{'e1', 'e2' }

The following examples are just like the previous set of examples but now include the ability to have a listqualifier that is both dimension and hierarchy qualified. The elements in the list must come from the samedimension. But there is no ability to provide an explicit hierarchy-qualified list that mixes elements fromdifferent hierarchies of the dimension.

{ 'e1', 'e2' }'d':{ 'e1', 'e2' }'d':'h':{ 'e1', 'e2' }

The following three examples show the ability to provide dimension and hierarchy qualification inside anunqualified list. The list elements must come from the same dimension, but now they can explicitly mixhierarchies of the same dimension. If a list qualifier is present, then this restricts what kind ofqualification is allowed inside the list:

{ 'e1', 'e2' }{ 'd':'e1', 'd':'e2' }{ 'd':'h1':'e1', 'd':'h2':'e2' }

In the following two examples, the list elements are restricted to being at most hierarchy qualified. Athree-part name won't compile because the dimension is already expressed by the list qualifier.

'd':{ 'e1', 'e2' }'d':{ 'h1':'e1', 'h2':'e2' }

The following example is in the current form.

'd':'h':{ 'e1', 'e2' }

124 IBM Planning Analytics TM1 REST API

Delete a cubeYou can use the DELETE operation to remove a cube.

Any GET action for a specific entity can be replaced with a DELETE action if the logged in user has theappropriate permissions. In the following example, the 'plan_BudgetPlan' cube is deleted with the sameresource path as would be used with a GET action.

DELETE /api/v1/Cubes('plan_BudgetPlan')

You can confirm a DELETE action by attempting a GET action on the same resource path, which returns anerror message if the deletion was successful:

{"error":{"code":"","message":"'plan_BudgetPlan' can not be found in collection of type 'Cube'."}}

Context dimensions and membersContext dimensions filter the context of a grid but do not appear on the rows or columns.

Row and column dimensions display all of their list items in the grid, but context dimensions limit theitems in the grid by displaying only information related to the active item in the dimension.

Traverse a cube to view dimensionsYou can use the following GET request to display values in a view:

GET /api/v1/Cubes('Metrics cube-Sales')/Views('Metrics cube-Sales') ?$expand=tm1.NativeView/Titles/Subset($expand=Elements($select=Name))

The results indicate the titles of the dimension subsets and members used in the view:

{ "@odata.context": "../$metadata#Cubes('Metrics%20cube-Sales')/Views/ibm.tm1.api.v1.NativeView (ibm.tm1.api.v1.NativeView/Titles/Subset(Elements+(Name,UniqueName)))/$entity", "@odata.type": "#ibm.tm1.api.v1.NativeView", "Name": "Metrics cube-Sales", "Columns": [ {} ], "Rows": [ {} ], "Titles": [ { "Subset": { "Name": "All Members", "Expression": "[country].MEMBERS", "Elements": [ { "Name": "Total of Country" }, { "Name": "Americas", }, ... ] } }, { "Subset": { "Name": "All Members", "Expression": "[product].MEMBERS", "Elements": [ { "Name": "Total of Product" }, ... ] }

Representing TM1 data 125

}, { "Subset": { "Name": "All Members", "Expression": "[Time].MEMBERS", "Elements": [ { "Name": "2013" }, { "Name": "Q1 2013" }, { "Name": "Jan 2013" }, ... ] } } ], "SuppressEmptyColumns": false, "SuppressEmptyRows": false, "FormatString": "0.00"}

These values correspond to the dimension titles and members in the pivot table example:

You can also stack $expand options in the same way a $select option can be stacked and return thecolumns, rows, and titles in the same expression:

/api/v1/Cubes('Metrics cube-Sales')/Views('Metrics cube-Sales') ?$expand=tm1.NativeView/Rows/Subset($expand=Elements($select=Name)), tm1.NativeView/Columns/Subset($expand=Elements($select=Name)), tm1.NativeView/Titles/Subset($expand=Elements($select=Name))

Create a dimensionTo create a dimension, specify the context of the dimension in the resource path of the URL and use aPOST operation.

In the following example, a Dimension is created:

POST /api/v1/Dimensions { "Name": "my_plan_department", "UniqueName": "[my_plan_department]", "Attributes": { "Caption": "My plan department" } }

126 IBM Planning Analytics TM1 REST API

The structure of the new entity must conform to the schema rules that are defined in the $metadatadocument from the server. If successful, a 201 Created HTTP response is returned, in addition to thenewly created entity:

{ "@odata.context": "$metadata#Dimensions/$entity", "Name": "my_plan_department", "UniqueName": "[my_plan_department]", "Attributes": { "Caption": "My plan department" }}

Add a dimension to a cubeTo add an dimension to an existing cube, you need to obtain the context of the cube, where it is contained,and specify POST data that defines the structure of the new item based on the rules that are defined inthe server's metadata document.

To create a new dimension in a cube for example, the cube must be specified in the resource path of theURL and the structure of the new dimension must be specified in the POST operation:

POST /api/v1/Cubes{ "Name": "test_cube", "Dimensions": [ { "Name": "test_cube_post_insert_dimension_1", }, { "Name": "test_cube_post_insert_dimension_2", } ]}

The resource context of the POST operation and the new dimension are returned in the result.

{ "@odata.context": "$metadata#Dimensions/$entity", "Name": "Sample dimension", "UniqueName": "[Sample dimension]", "Attributes": { "Caption": "Sample dimension" }}

Delete a dimensionYou can use the DELETE operation to remove a dimension.

The following example removes the 'Q1-2005' element from the time dimension. If you remove adimension, it removes any relationships it had with other entities.

DELETE /api/v1/Dimensions('plan_Time')/Hierarchies('plan_Time')/Elements('Q1-2005')

A successful DELETE action returns 204 No Content in the HTTP response header and an empty body.

Representing TM1 data 127

Column and row dimensionsWhen a dimension is used in a row or column, each of its list items has a heading. A cell is created forevery intersecting row and column.

Expand columns and rows in a queryYou can use the $expand option to specify the Column information in the response:

GET /api/v1/Cubes('Metrics cube-Sales')/Views('Metrics cube-Sales')? $expand=tm1.NativeView/Columns/Subset($expand=Elements)

In the following results, some results are truncated:

{ "@odata.context": "../$metadata#Cubes('Metrics%20cube-Sales')/Views/ibm.tm1.api.v1.NativeView(ibm.tm1.api.v1.NativeView/Columns/Subset(Elements))/$entity", "@odata.type": "#ibm.tm1.api.v1.NativeView", "Name": "Metrics cube-Sales", "Columns": [ { "Subset": { "Name": "All Members", "UniqueName": "[Metric Indicators].[All Members]", "Expression": "[Metric Indicators].MEMBERS", "Elements": [ { "Name": "Status", "UniqueName": "[Metric Indicators].[Status]", "Type": "Numeric", "Level": 0, "Index": 1, "Attributes": { ... } }, { "Name": "Trend", "UniqueName": "[Metric Indicators].[Trend]", "Type": "Numeric", "Level": 0, "Index": 2, "Attributes": { ... } }, { "Name": "Actual", "UniqueName": "[Metric Indicators].[Actual]", "Type": "Numeric", "Level": 0, "Index": 3, "Attributes": { ... } }, ...

The Name values of Columns can be seen here:

128 IBM Planning Analytics TM1 REST API

Use options to expand and filter detailsYou can expand the rows by using the $expand option:

GET /api/v1/Cubes('Metrics cube-Sales')/Views('Metrics cube-Sales')? $expand=tm1.NativeView/Rows/Subset($expand=Elements($select=Name))

In this example, a $select statement is used to filter the results to only Name and UniqueName:

{ "@odata.context": "../$metadata#Cubes('Metrics%20cube-Sales')/Views/ibm.tm1.api.v1.NativeView(ibm.tm1.api.v1.NativeView/Rows/Subset(Elements+(Name,UniqueName)))/$entity", "@odata.type": "#ibm.tm1.api.v1.NativeView", "Name": "Metrics cube-Sales", "Columns": [ {} ], "Rows": [ { "Subset": { "Name": "All Members", "Expression": "[metric-sales].MEMBERS", "Elements": [ { "Name": "Sales revenue" }, { "Name": "Quantity sold" }, { "Name": "Order count" }, { "Name": "Price discount" } ] } } ], "Titles": [ {}, {}, {}, {} ], "SuppressEmptyColumns": false, "SuppressEmptyRows": false, "FormatString": "0.00"}

Columns and Titles aren't displayed because the $expand option wasn't used in the expression. TheName values of the Rows are the source for the Row titles in this example:

Create a cube with dimensions and elementsYou can create an empty cube initially and then later populate it with dimensions and elements, or youcan create a cube with dimensions and elements.

To create a cube and specify the contents of the new cube, specify the context, understand the structurefrom the $metadata document, and use a POST operation.

Representing TM1 data 129

To understand the schema rules for a cube, review the definition of the Cube entity in the $metadatadocument:

<EntityType Name="Cube"> <Key> <PropertyRef Name="Name" /> </Key> <Property Name="Name" Nullable="false" Type="Edm.String" /> <Property Name="Rules" Nullable="true" Type="Edm.String" /> <Property Name="LastSchemaUpdate" Nullable="true" Type="Edm.DateTimeOffset" /> <Property Name="LastDataUpdate" Nullable="true" Type="Edm.DateTimeOffset" /> <Property Name="Attributes" Type="ibm.tm1.api.v1.Attributes" /> <NavigationProperty Name="Dimensions" Type="Collection(ibm.tm1.api.v1.Dimension)" /> <NavigationProperty ContainsTarget="true" Name="Views" Partner="Cube" Type="Collection(ibm.tm1.api.v1.View)" /> <NavigationProperty ContainsTarget="true" Name="PrivateViews" Partner="Cube" Type="Collection(ibm.tm1.api.v1.View)" /> <NavigationProperty Name="Annotations" Type="Collection(ibm.tm1.api.v1.Annotation)" /> <NavigationProperty ContainsTarget="true" Name="LocalizedAttributes" Type="Collection(ibm.tm1.api.v1.LocalizedAttributes)" /> </EntityType>

The Nullable attribute identifies the required properties. The Type attribute identifies whether theproperty is one of the built-in types or a type specific to the TM1 vocabulary. Follow each Type propertythat is specified by the NavigationProperty elements to determine the structure of the entities thatare contained within the cube. For example, the Dimensions navigation property is defined as containingitems of type Dimension:

<EntityType Name="Dimension"> <Key> <PropertyRef Name="Name" /> </Key> <Property Name="Name" Nullable="false" Type="Edm.String" /> <Property Name="UniqueName" Nullable="true" Type="Edm.String" /> <Property Name="Attributes" Type="ibm.tm1.api.v1.Attributes" /> <NavigationProperty ContainsTarget="true" Name="Hierarchies" Partner="Dimension" Type="Collection(ibm.tm1.api.v1.Hierarchy)" /> <NavigationProperty ContainsTarget="true" Name="LocalizedAttributes" Type="Collection(ibm.tm1.api.v1.LocalizedAttributes)" /></EntityType>

For each entity that is contained within the entity in context, and identified by the navigation property'sType value, traverse the model until the full structure of the entity is understood.

In the following example, a simple cube is created with a minimal number of hierarchies and elements:

POST /api/v1/Cubes

{ "Name": "test_cube_post_dimensions_deep_insert_cube", "Dimensions": [ { "Name": "test_cube_post_insert_dimension_1", "Hierarchies": [ { "Name": "test_cube_post_insert_dimension_1", "Elements": [ { "Name": "test_element_d1e1" }, { "Name": "test_element_d1e2" } ] } ] }, { "Name": "test_cube_post_insert_dimension_2", "Hierarchies": [ { "Name": "test_cube_post_insert_dimension_2", "Elements": [ { "Name": "test_element_d2e1" },

130 IBM Planning Analytics TM1 REST API

{ "Name": "test_element_d2e2" } ] } ] } ]}

After a successful POST operation, the context and the new entity that is created are returned in theresponse:

{ "@odata.context": "$metadata#Cubes/$entity", "Name": "test_cube_post_dimensions_deep_insert_cube", "Rules": "", "LastSchemaUpdate": "2014-05-06T17:58:49.296Z", "LastDataUpdate": "2014-05-06T17:58:49.135Z", "Attributes": { "Caption": "test_cube_post_dimensions_deep_insert_cube" }

CellsetsA cellset is the result of an execution of a view or an MDX expression, representing a snapshot of yourdata in a certain point in time. You can use the cellset ID within a session instead of running a view or MDXexpression multiple times.

When a view is executed, a snapshot of the data in the cube at a certain point in time is displayed basedon the dimensions specified for the view.

Find cell values in a cellsetYou can use the $expand query option to return all of the cell values in the cellset. To retrieve columnsand rows, see “Column and row dimensions” on page 128.

POST /api/v1/Cubes('Metrics cube-Sales')/Views('Metrics cube-Sales')/tm1.Execute?$expand=Cells

Returns the cell values, starting at ordinal 0, for the view specified.

{ "@odata.context": "../../$metadata#Cellsets(Cells)/$entity", "ID": "kyMtu_8DAIB7AQAg", "Cells": [ { "Ordinal": 0, "Value": -1, "FormattedValue": "($1.00)" }, { "Ordinal": 1, "Value": -1, "FormattedValue": "($1.00)" }, { "Ordinal": 2, "Value": 1723646.69, "FormattedValue": "$1,723,646.69" }, { "Ordinal": 3, "Value": 4405316.5, "FormattedValue": "$4,405,316.50" }, ... } ]}

Representing TM1 data 131

Ordinal values start from left to right, top to bottom on a chart display, as represented in the followingexample:

Run a view and expand the cellsetsThe service $metadata document defines actions and specifies where the actions can be applied in thedata model.

The Execute action is bound to the View entity type and provides a snapshot of the contents of the view(cellsets) at the point in time that the action runs:

POST /api/v1/Cubes('plan_BudgetPlan')/Views('plan_budget_input')/tm1.Execute

The result of the action provides the value of the ID property of the Cellset:

{ "@odata.context": "../../$metadata#Cellsets/$entity", "ID":"DWjRKwMCAIAFAAAg"}

Only the ID property is included in the result because the ID is the only primitive property that is definedfor a Cellset.

Add the $expand option to include the values and ordinals of the cells within the cellset:

POST /api/v1/Cubes('plan_BudgetPlan')/Views('plan_budget_input')/ tm1.Execute?$expand=Cells

Expand the cells to display the value of all the cells in the cellset in the result. Use $top and $skip tominimize the number of cells returned.

{ "@odata.context": "../../$metadata#Cellsets(Cells)/$entity", "ID": "DWjRKwMCAIAdAAAg", "Cells": [ { "Ordinal": 0, "Value": 146938800.55, "FormattedValue": "146,938,801" }, { "Ordinal": 1, "Value": 35723553.53, "FormattedValue": "35,723,554" }, { "Ordinal": 2, "Value": 11256636.11, "FormattedValue": "11,256,636" } ... ]}

Get the cells of a cellset in multiple partitionsYou can use the bound function GetPartition to get the cells of a cellset in multiple partitions.

You can use the GetPartition function to manage processing of area of the crosstab based on adefined boundary.

132 IBM Planning Analytics TM1 REST API

The cells property of the cellset can be used with the bound functionGetPartition( Begin=<ordinal>,End=<ordinal>) in a Get. For example:

/api/v1/Cellsets('FBxz3b4HAIBEAAAg')/tm1.GetPartition( Begin=0, End=10 )

The Begin ordinal defines the cell ordinal that makes up the left or right corner of the closest rectangulararea of your cells, and the End ordinal specifies the other edge.

0 12 34 56 78 910 1112 13

In this example, (Begin=0,End=10) gives you the column : cells 0,2,4,6,8,10.

If you supply (Begin=1,End=10), you get cells 0-11.

Use $top and $skip to minimize the number of cells returned.

Preview a datasourceYou can use the REST API actions ExecuteCubeDrillthrough andExecuteRelationalDrillthrough to preview a datasource.

These actions takes two parameters:

• A TI Process• The parameters for executing the TI Process

The TI Process can be a reference to an existing Process or a transient one. The parameters are optional.

The process of the ExecuteCubeDrillthrough returns a view handle that is used by the action to acreate a Cellset. The process of the ExecuteRelationalDrillthrough returns an SQL or CSVhandle that is converted to a collection of DrillthroughRows.

Example 1: Preview an ODBC (SQL) datasource

POST /api/v1/ExecuteRelationalDrillthrough{ "DrillthroughProcess": { "DataSource": { "Type": "ODBC", "dataSourceNameForServer": "Test", "query": "SELECT * FROM [Car Sales$];" }, "EpilogProcedure": "ReturnSqlTableHandle;" }}

Example 2: Drill to a drillthrough object (a TI process that returns view handle)

POST /api/v1/ExecuteCubeDrillthrough{ "DrillthroughProcess": { "Name": "Tmp_Drill", "EpilogProcedure": "#****Begin: Generated Statements***\r\nReturnViewHandle('C2_D2D3','C2_V3');\r\n#****End: Generated Statements****", "DataSource": { "Type": "TM1CubeView", "dataSourceNameForServer": "C2_D2D3", "view": "C2_V3"

Representing TM1 data 133

}, "Parameters": [ { "Name": "cubename", "Value": "C1_D1D2" }, { "Name": "D1", "Value": "D1_E1" }, { "Name": "D2", "Value": "D2_E1" } ] }, "Parameters": [ { "Name": "cubename", "Value": "C1_D1D2" }, { "Name": "D1", "Value": "D1_E1" }, { "Name": "D2", "Value": "D2_E2" } ]}

Example 3: Drill to an existing drillthrough object

POST /api/v1/ExecuteCubeDrillthrough{ "DrillthroughProcess@odata.bind": "Processes('ABC')"}

To support drillthrough to CSV, the TI function ReturnCSVTableHandle returns the handle of the CSVdatasource. The REST API reads the datasource and converts the data to drillthrough rows.

The naming scheme of the CSV columns follows the Excel scheme: A, B, ... Z, AA, AB, and so on.

For example:

POST /api/v1/ExecuteRelationalDrillthrough?$top=1{ "DrillthroughProcess": { "DataSource": { "Type": "ASCII", "asciiDecimalSeparator": ".", "asciiDelimiterChar": ",", "asciiDelimiterType": "Character", "asciiHeaderRecords": 1, "asciiQuoteCharacter": "\"", "asciiThousandSeparator": ",", "dataSourceNameForServer": ".\\data_load\\budget_input\\Plan_Load_Budget_ascii.csv" }, "EpilogProcedure": "ReturnCSVTableHandle;" }}

Response:

{ "@odata.context": "$metadata#Collection(ibm.tm1.api.v1.DrillthroughRow)", "value": [ { "A": "Jan-2003", "B": "105", "C": "10120", "D": "41101", "E": "658008" } ]}

Update a single cell valueYou can update a single cell value by using the PATCH operation.

To update the value of the cell, determine the value of the ID property of the cellset that the cell belongsto, and determine whether it is a value that can be updated.

POST /api/v1/Cubes('plan_Budgetplan')/Views('Budget input detailed')/ tm1.Execute?$expand=Cells($select=Ordinal,FormattedValue,Consolidated)

134 IBM Planning Analytics TM1 REST API

The request in the previous example returns the cells in the cellset as shown below.

{ "@odata.context": "../../$metadata#Cellsets(Cells(Ordinal,FormattedValue,Consolidated))/$entity", "ID": "DWjRKwMCAIAFAAAg", "Cells": [ { "Ordinal": 0, "FormattedValue": "938,285", "Consolidated": true }, { "Ordinal": 1, "FormattedValue": "315,513", "Consolidated": false }, { "Ordinal": 2, "FormattedValue": "311,041", "Consolidated": false }, ...

The Consolidated property identifies if the value is a result of an aggregation or other operation basedon other cell values. If the property is true, you cannot change the value unless Updateable=true. If aconsolidated value is updateable, you can update the value with a spreading command.

If the property is set to Consolidated=false, use a PATCH operation to update the cell, specifying theordinal and the new value.

PATCH /api/v1/Cellsets('DWjRKwMCAIAFAAAg')/Cells

[ { "Ordinal": 1, "Value": 315999 } ]

To verify that the cell is updated properly, repeat the GET operation.

Update many cell valuesYou can use the Update action to update multiple cells.

Since 10.2.RP2.FP4, the following Update actions are available:

• An Update (Cellset) action that is bound to the cellset• An Update (Cube) action that is directly bound to the cube• An Update (Cube) action that isn't bound to anything

These actions let you update one cell at a time. This cell can be a consolidated cell when you are using aspreading command. When you use the Update action on a cellset, the cellset also defines the bounds ofsome of the spreading commands and the cell ordinal can be used to specify which cell in the cube needsto be updated. The other two versions of the Update action require you to specify the cell by usingelements references instead.

The Update(Cube) actions accept an array of sets of arguments. You can make multiple updates in onerequest, as if you had called the same Update action multiple times.

Note: Using an Update action with an array of arguments is not OData compliant and therefore thisapproach is not documented in the metadata document.

Representing TM1 data 135

Delete a cellsetIf you run a view or MDX expression multiple times, it can yield different results each time and can havean impact on memory resources. After operations on a cellset finish, you must delete the cellset if you donot end the session, as shown in the following example:

DELETE /api/vi/Cellsets('ID#')

When a session ends, the cellset is deleted automatically, if it is not explicitly deleted beforehand.

ElementsAn element identifies the location of a cell in a cube and the position of the element within a dimension.

Retrieve elements by supplying either alias or invariant nameThe REST APIs use a built-in generic function, called subList that takes a set of entities as the input andbased on the keys that are specified in the Keys parameter, returns a list of items from the sourcecollection. That is, it uses the collection to which the function was bound or called upon, containing oneentity per Key entry and null if such an entity cannot be found. Therefore, the response format for the listis the same as for the source collection, which takes into account that the returned list can contain nulls,even if the source collection wasn't nullable. The Keys parameter is a JSON array and cannot be passed inplace but must be passed as a query option by using a parameter alias.

Example 1:

GET ~/api/v1/Dimensions/tm1.subList(Keys=@keys)?@keys=["Customers","Products","Non-Existing-Dimension",{"Name":"Customers"},"T i M e "]

From all the dimensions in the model, example 1 returns the Customers dimension, the Productsdimension, a null (you don't have the "Non-Existing-Dimension" dimension), the Customers dimensionagain (note: the object notation that represents the Keys, in this case just the Name, is allowed as well)and lastly, the Time dimension. Names, like resolution of entities themselves, are case- and space-insensitive and resolve aliases for those objects that support aliases.

Example 2:

GET ~/api/v1/Dimensions('Time')/Hierarchies('Quarters')/Elements/tm1.subList(Keys=@Keys)?@Keys=["Q1-1997","Q2-1997","Q3-1997","Q4-1997","Q5-1997"]

Form the Quarters hierarchy of the Time dimension's elements, example 2 returns the four quarters of1997 plus a null because Q5 doesn't exist.

Example 3:

GET ~/api/v1/Dimensions('Time')/Hierarchies('Time')/Edges/tm1.subList(Keys=@Keys)?@Keys=[{"ParentName":"Q1-1997","ComponentName":"01-1997"},{"ParentName":"Q1-1997","ComponentName":"04-1997"},{"ParentName":"Q2-1997","ComponentName":"04-1997"}]

For entity types that have multi-part keys (currently only Edges in TM1), you can use the object notation topair the keys to be used to look up entries. Example 3 returns three items. The second item is nullbecause the fourth month is not a child of the first quarter and therefore this edge does not exist.

Example 4:

GET ~/api/v1/Dimensions('Time')/Hierarchies('Time')/Levels(1)/Members/tm1.subList(Keys=@Keys)?@Keys=["1996","Q3-1996","1997","Q1-1997"]

Example 4 shows that the source set limits the entities that are returned. Level 1 of the Time hierarchyhas years only in the NorthWind sample database. Therefore, requesting a couple of years and quarters

136 IBM Planning Analytics TM1 REST API

results in nulls for the quarters even though the members by themselves exists in the hierarchy but not inthe level.

Using invalid JSON for the Keys parameter results in a 400 Invalid Request with an Invalid JSON message.Using incorrect types for the Keys parameter results in either an error message because the type is notacceptable as a key or results in null entries because the mapping to the actual keys and the lookupdoesn't render any valid entities.

You can use GET on this function, which is by convention. You can also use POST. You must keep in mindthat this is a function, therefore the open and close parentheses are required and the response is a 200OK (not 201 Created) because the request is not creating any new entries.

Using POST instead of GET in example 1 would look like:

POST ~/api/v1/Dimensions/tm1.subList(){"Keys":["Customers","Products","Non-Existing-Dimension",{"Name":"Customers"},"T i M e "]}

Update all elements in a static setYou can execute a PUT on the reference of the subset element collection to update the collection. You canexecute a DELETE on the reference of the collection to empty the collection. The $filter query option canbe used to specify which element should be removed.

This capability is a partial implementation of OData v4.01 11.4.6.4 on subset element collections.

A successful PUT request to a collection-valued navigation property’s reference resource replaces the setof related entities. The request body of the PUT must be a collection of entity references to elements ofthe hierarchy containing the subset.

For example, this request:

PUT /api/v1/Dimensions('D1')/Hierarchies('D1')/Subsets('S1')/Elements/$ref[ { "@odata.id": "Dimensions('D1')/Hierarchies('D1')/Elements('E3')" }, { "@odata.id": "Dimensions('D1')/Hierarchies('D1')/Elements('E4')" }, { "@odata.id": "Dimensions('D1')/Hierarchies('D1')/Elements('E5')" }]

Has the following expected response:

{ "@odata.context":"../../../../$metadata#Collection($ref)", "value": [ {"@odata.id":"Dimensions('D1')/Hierarchies('D1')/Elements('E3')"}, {"@odata.id":"Dimensions('D1')/Hierarchies('D1')/Elements('E4')"}, {"@odata.id":"Dimensions('D1')/Hierarchies('D1')/Elements('E5')"} ]}

A successful DELETE request to a collection-valued navigation property’s reference resource removes allrequested references from the collection. You can use the $filter query option to specify elements toremove.

For example, the following request is a filtered delete that deletes all elements named E3 in the S2 subsetof the D1 dimension:

DELETE /api/v1/Dimensions('D1')/Hierarchies('D1')/PrivateSubsets('S2')/Elements/$ref?$filter=Name eq 'E3'

Representing TM1 data 137

ChoresChores act like any other entity in the TM1 REST API. You can use create, read, update, and deleteoperations on chores. You can also execute a chore.

Chores are a container object for a set of TM1 processes. You can run processes in a certain order andschedule processes to be run at a certain time by using chores. For details, see Scheduling a Process forAutomatic Execution with Chores.

The Chore, ChoreTask, and ChoreReference entity types are used to perform the following actionswith the TM1 REST API:

• Retrieve a definition of an existing Chore (subjected to security context)• Retrieve the chore's basic properties• Retrieve the chore's tasks (by using a ChoreTask)• Retrieve the chore's execution mode• Retrieve a set of chores (subjected to security context)• Filter a set of chores (subjected to security context)• Retrieve a set of chore properties (subjected to security context)• Create a chore (subjected to security context)• Modify an existing chore (subjected to security context)• Modify a chore's basic properties• Add a chore task• Remove a chore task

The following examples demonstrate how to use chores in the TM1 REST API. These operations areavailable with 10.2.2 FP2. For these examples to work, two TurboIntegrator processes need to be inplace, myProcess1 and myProcess2. To learn how to add a TurboIntegrator process to your TM1 model,see Creating a TurboIntegrator Process in the TM1 TurboIntegrator documentation and “Create an entity(HTTP POST)” on page 3.

Create a chorePOST

http://tm1server:8000/api/v1/Chores

POST data

{ "Name": "myChore", "StartTime": "2012-07-27T23:03:00-04:00", "Frequency": "P223DT10H12M23S", "ExecutionMode": "MultipleCommit", "Tasks": [ { "Process@odata.bind": "Processes('myProcess1')", "Parameters": [ { "Name": "pParam1", "Value": "pValue1" }, { "Name": "pParam2", "Value": "pValue2" } ] }, { "Process@odata.bind": "Processes('myProcess2')" }

138 IBM Planning Analytics TM1 REST API

]}

Get the names of processes contained in a choreGET

http://tm1server:8000/api/v1/Chores('myChore')/Tasks?$expand=Process($select=Name)

Activate a chorePOST

http://tm1server:8000/api/v1/Chores('myChore')/tm1.Activate

POST dataNot applicable.

Deactivate a chorePOST

http://tm1server:8000/api/v1/Chores('myChore')/tm1.Deactivate

POST dataNot applicable.

Change some properties of a chorePATCH

http://tm1server:8000/api/v1/Chores('myChore')

PATCH data

{ "ExecutionMode" : "SingleCommit", "StartTime": "2013-07-27T23:03:00Z", "Frequency": "P1DT2H3M4S"}

Add tasks to a chorePOST

http://tm1server:8000/api/v1/Chores('myChore')/Tasks

POST data

[ { "Process@odata.bind": "Processes('MyProcess1')", "Parameters": [ { "Name": "pParam1", "Value": "pValue1" }, { "Name": "pParam2", "Value": "pValue2" } ] }, { "Process@odata.bind": "Processes('MyProcess2')" }]

Representing TM1 data 139

Remove a Task from a choreDELETE

http://tm1server:8000/api/v1/Chores('myChore')/Tasks(1)

Change the settings of a TaskPATCH

http://tm1server:8000/api/v1/Chores('myChore')/Tasks(1)

PATCH data

{ "Process@odata.bind" : "Processes('plan_load_actual_ascii')", "Parameters": [ { "Name": "pParam1", "Value": "pNewValue1" }, { "Name": "pParam2", "Value": "pNewValue2" } ]}

Execute a chorePOST

http://tm1server:8000/api/v1/Chores('myChore')/tm1.Execute

POST dataNot applicable.

List all chores that contain a certain TurboIntegrator processGET

http://tm1server:8000/api/v1/Chores?$filter=Tasks/any(t: t/Process/Name eq 'myProcess')

Folders and contentsYou can use the Folders and Contents to load all elements from the Applications folder.

Note: Unlike in cubes and dimensions, the indices that are used in folders are case-sensitive.

The following examples can help you get started:

Link to get the document reference

This example expands three levels, where 'Applications' is considered the first level.

http://tm1server:8000/api/v1/Contents('Applications')?$expand=tm1.Folder/Contents($expand=tm1.Folder/Contents($expand=tm1.Folder/Contents($expand=tm1.Folder/Contents,tm1.DocumentReference/Document)))

140 IBM Planning Analytics TM1 REST API

Get document references for a level

This example gets the document references at the third level, where the first level is always reserved forthe 'Applications' folder.

http://tm1server:8000/api/v1/Contents('Applications')?$expand=tm1.Folder/Contents($expand=tm1.DocumentReference/Document,tm1.Folder/Contents($expand=tm1.Folder/Contents($expand=tm1.Folder/Contents,tm1.DocumentReference/Document)))

Get document references in a particular folder

http://tm1server:8000/api/v1/Contents('Applications')/Contents('Planning%20Sample')/Contents('Bottom%20Up%20Input')/Contents?$expand=tm1.DocumentReference/Document

Get document and view references on three levels

http://tm1server:8000/api/v1/Contents('Applications')?$expand=tm1.Folder/Contents($expand=tm1.ViewReference/View,tm1.DocumentReference/Document,tm1.Folder/Contents($expand=tm1.Folder/Contents($expand=tm1.Folder/Contents,tm1.DocumentReference/Document,tm1.ViewReference/View)))

Get the count of public and private entries in subfolders of a specific folder

This example gets the count of entries in all subfolders in the 'Applications' folder. You can use thisquery to determine whether a subfolder contains content.

http://tm1server:8000/api/v1/Contents('Applications')?$expand=Contents($expand=tm1.Folder/Contents/$count,tm1.Folder/PrivateContents/$count)

Download the content of a document

http://tm1server:8000/api/v1/Contents('Applications')/Contents('PlanningSample')/Contents('Administrator')/Contents('Exchange Rates')/Contents('Set Rates By Currency.blob')/Document/Content

Functions and actionsThe TM1 entity model exposes various functions and actions that are specific to TM1.

Actions and functions are defined in the TM1 Entity Data Model (EDM) and describe operations that canbe performed against the model. All functions and actions are defined according to the rules that aredefined in OData Version 4 for custom operation. For more information, see Chapter 4, “Metadata,” onpage 11.

Functions in OData (edm:Function) are operations that do not have any observable side effects andmust return a single or multiple instances of a type that is specified by the functions edm:ReturnTypeelement. For more information about TM1 functions, see Functions.

An action (edm:Action) is an operation in OData that might have an observable side effect in an entitymodel and might return a value if an edm:ReturnType element is defined for the action. For moreinformation about TM1 actions, see “Actions” on page 83.

Each <Action> and <Function> element contains an IsBound attribute for which the default value isfalse. If an action or function is defined as IsBound=true, the operation can be invoked only on thefirst element defined as a parameter for that operation. For example, the Execute action is bound to aView entity, meaning that the action can be performed only on that type of entity:

<Action Name="Execute" IsBound="true"> <Parameter Name="View" Type="ibm.tm1.api.v1.View" Nullable="false"/> <Parameter Name="Titles" Type="Collection(ibm.tm1.api.v1.Element)" Nullable="true"/> <Parameter Name="SuppressEmptyColumns" Type="Edm.Boolean" Nullable="true"/> <Parameter Name="SuppressEmptyRows" Type="Edm.Boolean" Nullable="true"/>

Representing TM1 data 141

<ReturnType Type="ibm.tm1.api.v1.Cellset" Nullable="false"/></Action>

In the CSDL file, the Execute action is also defined in the context of a Process entity. This is the sameas overloading in many programming languages, and indicates that this action can be invoked againsteither type of entity:

<Action Name="Execute" IsBound="true"> <Parameter Name="Process" Type="ibm.tm1.api.v1.Process" Nullable="false"/> <Parameter Name="Parameters" Type="Collection(ibm.tm1.api.v1.NameValuePair)" Nullable="true"/> </Action>

Bound functions and actions support overloading according to the rules defined in the ODataspecification.

In the previous example, because the action is bound to the View entity, it can be invoked only in thatcontext:

/api/v1/Cubes('MyCube')/Views('MyView')/tm1.Execute

An operation that is imported into the API entity container (<EntityContainer Name="API">) isunbound and can be addressed at the root level, but only on the type of entity set that is defined for thataction. In the following example, the ExecuteMDX action can be invoked only on the Cellsets entitytype:

<ActionImport Name="ExecuteMDX" Action="ibm.tm1.api.v1.ExecuteMDX" EntitySet="Cellsets"/>

As a result, the action does not require an entity to be in context, and can be specified at the root level ofthe API:

/api/v1/ExecuteMDX()

For more information, use the following resources:

• OData Version 4: 11.5 Operations• OData Version 4: 12.1.2 Attribute IsBound

Options and filtersYou can use batch query/update options to group queries, pagination query options to limit the results ofyour query, and filtering options to manage the results of your query.

For more information about options and filters, use the following ODATA references:

• 19 Batch Requests and Responses• 5.1.2 System Query Option $expand• 5.1.5 System Query Options $top and $skip• 5.1.1 System Query Option $filter• 5.1.1.4.3 startswith

Batch optionsYou can use OData v4.01 based $batch options.

The implementation of $batch options in the OData v4.0 based TM1 REST API implementation follows thev4.01 specification and takes the following limitations into account:

• Supports only the v4.01 JSON format, not the v4.0 multi-part format.• Does not support atomicity groups, therefore the atomicityGroup property must not be defined in

requests.

142 IBM Planning Analytics TM1 REST API

• Does not support dependencies, therefore the dependsOn property must not be defined in requests.

No dependencies implies no referencing to results of previous requests. That is, no $id as first segmentof a relative path.

• Does not support nested $batch requests in a batch request.• Asynchronously executed requests, execute asynchronously and do not return interim results.

The v4.01 specification allows and describes a mechanism to return interim results but doesn't requirea service to implement.

• The TM1SessionId cookie can be set on the $batch request itself and must not be set on theindividual requests.

• The Authorization header, which triggers Authentication, must be set on the $batch request itself andmust not be set on any of the individual requests.

• If the content-type, which by definition is application/json, is the same as on the $batch response(including parameters), it is ignored.

According to the specification, this header must be included if it is not exactly application/json andhas no parameters, which it never is for TM1 REST APIs but it is typically the same as what is put on the$batch response itself.

• Requests that return binary responses are not supported (currently only limits requests for content offiles and attachments).

For more information, see the OData v4.01 protocol specification and Chapter 19 of the OData JSONFormat v4.01.

Pagination query optionsYou can use pagination query options to limit the results of your query.

For queries that return many results, the OData specification provides navigation options to limit andmanipulate the results by using pagination system query options, such as $top and $skip.

To limit the size of the results, use the $top option.

Cubes?$select=Name&$top=2

This example displays the first two cubes from the model.

{ "@odata.context": "$metadata#Cubes", "value": [ { "Name": "plan_BudgetPlan" }, { "Name": "plan_BudgetPlanLineItem" } ]}

The $skip option sets the beginning of the list returned to the specified value.

Cubes?$select=Name&$top=2&$skip=2

In this example, the next two cube names (the third and fourth cubes) are listed in the results.

{ "@odata.context": "$metadata#Cubes", "value": [ { "Name": "plan_Control" }, { "Name": "plan_ExchangeRate" }

Representing TM1 data 143

]}

Filter expressionsYou can use filtering options to manage the results of your query.

The OData specification includes a number of filtering options to manage result output. For moreinformation, see 5.1.1 System Query Option $filter.

To list dimensions where the name of the dimensions begins with the string plan, use the startswithfunction:

Dimensions?$filter=startswith(Name,'plan')&$top=2

To limit the size of the results, use the $top query option.

{ "@odata.context": "$metadata#Dimensions", "value": [ { "Name": "plan_business_unit", "UniqueName": "[plan_business_unit]", "Attributes": { "Caption": "plan_business_unit" } }, { "Name": "plan_chart_of_accounts", "UniqueName": "[plan_chart_of_accounts]", "Attributes": { "Caption": "plan_chart_of_accounts" } } ]}

The following example returns TM1 control cubes, which are identified by names that begin with the "}"character.

Cubes?$filter=startswith(Name, '}')

Combine the previous example with the $select option to return only the names (Name property) of thecubes that match the filter.

Cubes?$filter=startswith(Name, '}')&$select=Name&$top=3

Add the $top query option to display only the first three control cubes:

{ "@odata.context": "$metadata#Cubes", "value": [ { "Name": "}ApplicationSecurity" }, { "Name": "}Capabilities" }, { "Name": "}ChoreSecurity" } ]}

144 IBM Planning Analytics TM1 REST API

Attributes and localizationYou can localize an IBM TM1 Server by assigning locale-specific values to attributes that are associatedwith cubes, dimensions, views, TI processes, subsets, and elements.

For TM1 Server to return the localized caption value for a view, subset, or TI process, the Captionattribute must be added if it does not exist. This Caption attribute can be set up as a Text type or as anAlias type. When this attribute is of type Alias, TM1 enforces the uniqueness of its values, and you canuse the Caption value to search for the associated TM1 object. When this Caption attribute is just aText type, its values are for displaying locale-specific caption and cannot be used in searching for TM1Objects.

TM1 Server uses international language codes that are defined by ISO 639-1 to identify major languagesand the IETF language tag in assigning locale-specific value. For example, "fr" is for French and "fr-FR" isfor French (France). When you assign a localized value to an attribute, it is only necessary to assign to themajor language code, for example, for "fr". TM1 Server automatically retrieves the value for the majorlanguage if it is asked for a specific locale such as "fr-FR" or "fr-CA" if values associated to those localesdo not exist. By default, if no localized values are found for an attribute, the base default attribute value isreturned.

Create Attributes and Captions for an entityYou can assign localized values to any attribute for all language locales, as elements in the }Culturescontrol dimension.

To change the set of locales, you can remove unused locales or add new ones. Make sure that youmaintain any locales references as parent locales.

Follow these steps to add attributes and localized values that are associated with those attributes byusing the TM1 REST API. In this example, the attributes and localized values are added to a cube, but thesame steps apply to other entities as well.

1. Create a }CubeAttributes dimension and specify the set of attributes that are associated withcubes.

Although the Caption attribute is built in, it needs to physically exist only if you want to explicitlyspecify values for it. In this example, to localize the Caption attribute you must explicitly add it.

POST /api/v1/Dimensions { "Name": "}CubeAttributes", "Hierarchies": [ { "Name": "}CubeAttributes", "Elements": [ { "Name": "Caption", "Type": "String" } ] } ]}

2. Create a }CubeAttributes cube.

This cube stores values for attributes that are associated with the cubes in the model.

POST /api/v1/Cubes

{ "Name": "}CubeAttributes", "Dimensions@odata.bind": [ "Dimensions('}Cubes')", "Dimensions('}CubeAttributes')" ]}

Representing TM1 data 145

A new control cube is created.

{ "@odata.context": "$metadata#Cubes/$entity", "Name": "}CubeAttributes", "Rules": "", "LastSchemaUpdate": "2014-05-06T21:11:30.795Z", "LastDataUpdate": "2014-05-06T21:11:30.774Z", "Attributes": { "Caption": "}CubeAttributes" }}

3. Execute a view or MDX query that returns a cellset that contains the cells and values for thoseattributes you want to update. For example, retrieve all of the attribute values for all cubes.

POST /api/v1/ExecuteMDX?$expand=Axes($expand=Hierarchies/ $ref,Tuples($expand=Members/$ref)),Cells

{ "MDX": "select [}CubeAttributes].members on 0, [}Cubes].members on 1 from [}CubeAttributes]" }

The axes are included in the response for use in the next step. The following example uses the IDvalue DWjRKwMCAIADAAAg. In your own procedure, use the ID property value that is returned in theCellset in the response.

4. Locate cells that you want to update. In this example the Caption for the plan_BudgetPlan cube isset.

PATCH /api/v1/Cellsets('DWjRKwMCAIABAAAg')/Cells

[ { "Ordinal": 1, "Value": "Budget Plan Cube" }]

Run the MDX query again to see the new value.

{ "@odata.context": "$metadata#Cellsets(Axes(Hierarchies,Tuples+(Members)),Cells)/$entity", "ID": "DWjRKwMCAIADAAAg", "Cells": [ { "Ordinal": 0, "Value": "", "FormattedValue": "" }, { "Ordinal": 1, "Value": "Budget Plan Cube", "FormattedValue": "Budget Plan Cube" }, ...

5. Validate that the Caption attribute is updated.

The Caption attribute must now contain the value that is specified in the previous request.

GET /api/v1/Cubes('plan_BudgetPlan')

6. To create the }LocalizedCubeAttributes cube, use the following request.

POST /api/v1/Cubes

{ "Name": "}LocalizedCubeAttributes", "Dimensions@odata.bind": [ "Dimensions('}Cubes')", "Dimensions('}Cultures')",

146 IBM Planning Analytics TM1 REST API

"Dimensions('}CubeAttributes')" ]}

The response displays the results of creating the new control cube. This control cube stores thelocalized values for attributes that are associated with cubes in the model.

{ "@odata.context": "$metadata#Cubes/$entity", "Name": "}LocalizedCubeAttributes", "Rules": "", "LastSchemaUpdate": "2014-05-07T02:12:51.463Z", "LastDataUpdate": "2014-05-07T02:12:51.446Z", "Attributes": { "Caption": "}LocalizedCubeAttributes" }}

7. Execute a view or MDX query that returns a cellset that contains the cells or values for the attributesyou want to update. In this example, all attributes for the plan_budgetPlanLineItem cube for theDutch (nl) locale are retrieved.

POST /api/v1/ExecuteMDX?$expand= Axes($expand=Hierarchies/$ref, Tuples($expand=Members/$ref)), Cells

{ "MDX": "select [}CubeAttributes].members on 0, {[}Cubes].[plan_BudgetPlan]} * {[}Cultures].[nl]} on 1 from [}LocalizedCubeAttributes]" }

8. Update cells that contain the localized values for the attributes you want to update. The ID used in theexample needs to be changed to a value in your own model. In this example, the Dutch caption for theplan_budgetPlanLineItem cube is updated.

PATCH /api/v1/Cellsets('DWjRKwMCAICHAAAg')/Cells

[ { "Ordinal": 0, "Value": "Budget Kubus" }]

9. Set the language setting in your browser to Dutch (nl) and validate that the caption is set correctly.

GET /api/v1/Cubes('plan_budgetPlanLineItem')

The localized value for the Caption must be returned in the result.

{ "@odata.context": "$metadata#Cubes/$entity", "Name": "plan_BudgetPlan", ... "LastSchemaUpdate": "2014-05-07T02:27:39.088Z", "LastDataUpdate": "2014-05-05T15:17:29.568Z", "Attributes": { "Caption": "Budget Kubus" }}

To optimize performance and combine steps “7” on page 147 and “8” on page 147, you can execute aPOST query to create a localized attribute if the locale ID exists. If the locale ID that you supply exists andis supported by TM1 Server but the attribute does not exist, the localized attribute is created using thatlocale ID and then the localized value is added. If the locale ID does not exist, an exception is thrown. Thefollowing example creates a localized attribute for the caption.

POST /api/v1/Cubes('plan_BudgetPlan')/LocalizedAttributes

{ "LocaleID":"en", "Attributes": {

Representing TM1 data 147

"Caption": "Budget Plan" }}

Use TurboIntegrator functionsYou can use TurboIntegrator functions to create localized attributes.

If you want your applications to automatically display captions of cubes, dimensions, views,TurboIntegrator processes, subsets, and elements with the right locale, you can set up the Captionattribute by using TurboIntegrator functions. The Caption attribute can be either text or alias.

Note: The PullInvalidationSubsets parameter in the tms1.cfg file must be enabled. To minimize lockcontention, you should review your existing TurboIntegrator processes to use temporary Views andSubsets where applicable.

View attributes

You can use the following functions to create and update view attributes:

• ViewAttrInsert( <cubeName>, <prevAttrName>, <newAttrName>, <attrType> )

• ViewAttrDelete( <cubeName>, <attrName> )

• ViewAttrPutS( <stringValue>, <cubeName>, <viewName>, <attrName>, [localeLangCode] )

• ViewAttrPutN( <numericValue>, <cubeName>, <viewName>, <attrName>, [localeLangCode] )

Each of these functions returns 1 for success, 0 for failure or throws an exception. The[localeLangCode] parameter is optional. When the [localeLangCode] parameter not specified invalue or left out altogether, the base attribute value is updated.

Any attribute can have a value assigned to it with a specific language or language locale code by using theoptional language code as a parameter. Using the Caption attribute as an example, you can use thefollowing sequence to create the attribute and assign the value with the "fr" language code:

ViewAttrInsert('plan_BudgetPlan', '', 'Caption', 'S' )

ViewAttrPutS( 'Entrée budgétaire détaillée', 'plan_budgetPlan', 'Budget Input Detailed', 'fr' )

The call is repeated for each view and for each of the language locales for that view.

Note: You use this function only for the view where a localized attribute value is desired. The default valueis returned for other views. In addition, in the view caption case, if there are no attribute values defined inthe base attribute, the initial design invariant name is returned.

Subset Attributes

You can use the following functions to create and update subset attributes:

• SubsetAttrInsert( <dimensionName>, <prevAttrName>, <newAttrName>, <attrType> )

• SubsetAttrDelete( <dimensionName>, <attrName> )

• SubsetAttrPutS( <stringValue>, <dimensionName>, <subsetName>, <attrName>, [localeLangCode] )

• SubsetAttrPutN( <numericValue>, <dimensionName>, <subsetName>, <attrName>, [localeLangCode] )

148 IBM Planning Analytics TM1 REST API

Each of these functions returns 1 for success, 0 for failure or throws an exception. The[localeLangCode] parameter is optional. When the [localeLangCode] is not specified in value orleft out altogether, the base attribute value is updated.

Any attribute can have a value assigned to it with a specific language or language locale code using theoptional language code as a parameter. Using the Caption attribute as an example, you can use thefollowing sequence to create the attribute and assign the value with the "fr" language code:

SubsetAttrInsert( 'plan_business_unit', '', 'Caption', 'S')

SubsetAttrPutS( 'Toutes les unités d''affaires', 'plan_business_unit', 'All Business Units', 'fr' )

SubsetAttrPutS() is called for each subset and for each of the language locales for that subset.

Note: You use this function only for the subset where a localized attribute value is desired. The defaultvalue is returned for other subsets. In addition, in the subset caption case, if there are no attribute valuesdefined in the base attribute, the initial design invariant name is returned.

Process Attributes

You can use the following functions to create and update process attributes:

• ProcessAttrInsert( <prevAttrName>, <newAttrName>, <attrType> )

• ProcessAttrDelete( <attrName> )

• ProcessAttrPutS( <stringValue>, <processName>, <attrName>, [localeLangCode] )

• ProcessAttrPutN( <numericValue>, <processName>, <attrName>, [localeLangCode] )

Each of these functions returns 1 for success, 0 for failure or throws an exception. The[localeLangCode] parameter is optional. When the [localeLangCode] is not specified in value orleft out altogether, the base attribute value is updated.

Any attribute can have a value assigned to it with a specific language or language locale code using theoptional language code as a parameter. Using the Caption attribute as an example, you can use thefollowing sequence to create the attribute and assign the value with the "fr" language code:

ProcessAttrInsert( '', 'Caption', 'S')

ProcessAttrPutS( 'planifier la langue', 'plan_set_language', 'fr' )

ProcessAttrPutS() is called for each process and for each of the desired language locales for thatprocess.

Note: You use this function only for the process where a localized attribute value is desired. The defaultvalue is returned for other processes. In addition, in the process caption case, if there are no attributevalues defined in the base attribute, the initial design invariant name is returned.

More informationFor more information, see the following resources.

• Attribute Manipulation TurboIntegrator Functions• Planning Analytics Local Installation and Configuration documentation• OData Version 4.0 Part 2: URL Conventions/Service Root URL

Representing TM1 data 149

150 IBM Planning Analytics TM1 REST API

Chapter 6. Data spreading with the TM1 REST APIOne of the most powerful and complex features of TM1 is data spreading.

You can use data spreading to write large amounts of data into your TM1 database quickly. This feature iscommonly used in planning and budgeting applications. For example, when you are projecting expensesbased on last year's actual results, you can use data spreading to move last year's results, plus a smallpercentage, into this years projected budget. This technique gives you a baseline for projecting expensesfor the next fiscal period.

To perform data spreading with the TM1 REST API, use the following actions:

• Cellset.Update• Cellset.UpdateCells• Cube.Update• Cube.UpdateCells• Update

Spreading overviewTo successfully execute data spreading using the TM1 REST API, you must understand all of the followinginformation.

• The type of spreading that you want to perform. There are many different kinds of spreading in TM1. Thearguments that you supply to the TM1 REST API vary depending on the type of spreading you choose.

• The syntax of the spreading control code you want to execute. The spreading control code contains thevalue to be spread, information on what cells are affected by the spread, and what type of spreadingyou are using.

• The values of ProportionSpreadToZeroCells and SpreadingPrecision in the tms1.cfg file.

The rules for executing a spreading function across a cell range vary depending on the range of cells towhich you are spreading data. There are three separate cases discussed here:

• Spreading to a single leaf cell• Spreading to a single consolidated cell• Spreading to a range of cells

Each of these cases is described in the sections that follow.

Spreading to a single leaf cellSpreading to a single leaf cell updates the cell unless it is not updatable because of security limitations orsome other constraint, or if a hold is applied to it.

A leaf cell on hold is never updated by a spread function. It may be updated by manually changing the cellthrough the user interface, or by updating a single cell value with the TM1 REST API.

If one of the ancestors of the leaf cell is on consolidation hold, other leaf components of the ancestor areadjusted to keep the consolidated value constant.

Spreading to a consolidated cellWith the exception of functions that act on leaves, spreading to a consolidated cell means proportionallyspreading to all updateable leaves that have no holds applied.

Procedure

1. Get the value of the consolidated cell before spreading.

© Copyright IBM Corp. 2007, 2019 151

2. Calculate the sum of all the consolidation's leaf cells that are updateable and do not have a holdapplied.

3. Calculate the non-updateable sum by subtracting <2> from <1>.4. Subtract <3> from the spreading value.5. Spread <4> to the leaf cells that are updateable and do not have a hold applied. Spread to these cells

in proportion to their values before the spreading.

Spreading to a rangeWhen you spread data to a range, the cells in the range are filtered before the spread occurs.Filter 1

If the range to which the data will be spread contains cells of mixed levels of consolidation, all cellsare dropped except the cells at the lowest level.

Filter 2aIf the lowest level in the range are leaf cells, cells that are not updateable because of security or otherconstraints are dropped. Similarly, cells that have holds applied to them are dropped.

Filter 2bIf the lowest level remaining in the range are consolidated cells, all cells that have a consolidated holdare dropped.

Spreading is performed on the remaining cells in the range.

After spreading is completeInternally, TM1 performs a series of checks to determine if a spreading function was performed properly.

• The values are checked to test whether the leaf cells contain zero values. TM1® applies an equal spreadto the empty cells when the ProportionSpreadToZeroCells parameter is enabled. Thisfunctionality is enabled by default.

• The values after the spreading of all consolidated cells that participated in the spreading are comparedto their desired values.

• The values before and after the spreading are compared for all cells with consolidate holds. If any of thecomparisons failed to be within the predefined relative accuracy, the spreading is deemed failed and allchanges are rolled back. The default for the predefined relative accuracy is 1e-8, but this value isconfigurable for the server through the tm1s.cfg parameter SpreadingPrecision.

Spreading examplesThis section provides spreading examples using the TM1 REST APIs.

The values required vary according to the type of spreading you choose. The examples that followdescribe each type of spreading, and how the arguments to the REST APIs must be set to successfullyspread data.

Note: You can do multiple updates in one spreading request by using the $batch option or by using anarray in your request. For more information about the $batch option, see “Batch options” on page 142.

Proportional spread, equal spread, and repeatThe proportional spread method distributes a specified value among cells proportional to existing cellvalues. The equal spread method distributes a specified value equally across cells in a view. The repeatmethod repeats a specified value across cells in a view.

All three of these spreading examples use the same arguments. For more information, see “Spreadingcommand codes” on page 156.

152 IBM Planning Analytics TM1 REST API

Example: Proportional spread

This example proportionally spreads the value 100 to all leaf cells on the row of insertion, replacingexisting cell values.

POST api/v1/Cellsets('AAAAAA')/tm1.Update{ "BeginOrdinal":0, "Value":"P<>100"}

Example: Equal spread

This example equally spreads the value 200 to all leaf cells on the column of insertion, adding the productof spreading to existing cell values.

POST api/v1/Cellsets('AAAAAA')/tm1.Update{ "BeginOrdinal":0, "Value":"S+|^200"}

Example: Repeat

This example adds the value 50 from all leaf cells left of the insertion point.

POST api/v1/Cellsets('AAAAAA')/tm1.Update{ "BeginOrdinal":0, "Value":"R+<50"}

ClearThe clear method clears values from cells in a view. You can apply this method to either leaf cells orconsolidated cells. When you apply the clear method to a consolidated cell, all leaves of the consolidationget set to zero.

The spread code for clear spread is C. For more information, see “Spreading command codes” on page156.

Example

This example clears values from all cells in the view.

POST api/v1/Cellsets('AAAAAA')/tm1.Update{ "BeginOrdinal":0, "Value":"C|^<>"}

Percent changeThe percent change method multiplies the current cell values by a specified percentage. The product ofthat multiplication can then replace, be added to, or be subtracted from the existing cell values.

The spread code for percent change is P%. If you want to add to the total already in the cell, be sure toinclude the + sign in your command string.

For more information, see “Spreading command codes” on page 156.

Data spreading with the TM1 REST API 153

Example

This example applies a percent change of 10% to all leaf values in the view and adds the product toexisting cell values.(It increments all leaves in the view by 10%.)

POST api/v1/Cellsets('AAAAAA')/tm1.Update{ "BeginOrdinal":0, "Value":"P%+|^<>10"}

Straight lineThe straight line data spreading method populates cube cells by linear interpolation between twospecified endpoints.

The spread code for straight line is SL. For more information, see “Spreading command codes” on page156.

Example

This example applies Straight Line spreading to replace all leaf values right of the point of insertion, usinga start value of 100 and an end value of 200.

POST api/v1/Cellsets('AAAAAA')/tm1.Update{ "BeginOrdinal":0, "Value":"SL>100:200"}

Growth%The growth % method accepts an initial value and a growth percentage. Using the initial value as astarting point, this method then sequentially increments all values in a range by the specified growthpercentage.

The spread code for Growth% is G%. For more information, see “Spreading command codes” on page156.

Example

This example applies a 25% growth percentage to the starting value of 300 and replaces all leaf valuesbelow the point of insertion.

POST api/v1/Cellsets('AAAAAA')/tm1.Update{ "BeginOrdinal":0, "Value":"GR|300:25"}

Relative proportional spreadThe relative proportional spread method spreads values to the leaves (children) of a consolidationproportional to the leaves of a reference cell.

The reference cell can be located in the cube from which you initiate spreading or in a separate cube. Thereference cell must, however, share the same exact consolidations as the cell from which you initiatespreading.

The spread code for relative proportional spread is RP. For more information, see “Spreading commandcodes” on page 156.

154 IBM Planning Analytics TM1 REST API

Example

Start with a general proportional spreading command passing in the ReferenceCell as in the followingexample:

POST: Cellsets('AAAAAAA')/tm1.Update{ "BeginOrdinal":0, "Value":"RP9999" "ReferenceCell@odata.bind": [ "Dimensions('A')/Hierarchies('A')/Elements('E1')", "Dimensions('B')/Hierarchies('B')/Elements('E2')", "Dimensions('C')/Hierarchies('C')/Elements('E3')" ]}

You must specify the reference cell, and optionally the reference cube, if the cell resides in a differentcube on which the relative spread needs to take place. In the REST API, you specify a reference using the@odata.bind notation. For example, the ReferenceCell can be specified as:

"ReferenceCell@odata.bind":[ "Dimensions('A')/Hierarchies('A')/Elements('E1')", "Dimensions('B')/Hierarchies('B')/Elements('E2')", "Dimensions('C')/Hierarchies('C')/Elements('E3')"]

Or the ReferenceCube can be specified as:

"ReferenceCube@odata.bind": "Cubes('CUBE-NAME')"

Relative percent adjustmentThe relative percent adjustment method spreads values to the leaves of a consolidation by applying apercentage adjustment to the leaves of a reference cell.

The spread code for relative percent adjustment is R%. For more information, see “Spreading commandcodes” on page 156.

Example

This example takes the value of the reference cell's analogous leaf cell for each leaf cell in theconsolidation, adds 20%, and adds the total to the leaf cell in the current consolidation.

POST api/v1/Cellsets('AAAAAA')/tm1.Update{ "BeginOrdinal":0, "Value":"R%+20" "ReferenceCell@odata.bind": [ "Dimensions('A')/Hierarchies('A')/Elements('E1')", "Dimensions('B')/Hierarchies('B')/Elements('E2')", "Dimensions('C')/Hierarchies('C')/Elements('E3')" ]}

Repeat leavesThe repeat leaves method copies a specified value to the leaves (children) of a consolidation. When youapply this method, you can copy the value to all leaves of the consolidation or only to those leaves thatalready contain non-zero values.

The spread code for repeat leaves is LR. For more information, see “Spreading command codes” on page156.

Data spreading with the TM1 REST API 155

Example

This example adds 200 to all leaves in the current consolidation.

POST api/v1/Cellsets('AAAAAA')/tm1.Update{ "BeginOrdinal":0, "Value":"LR+*200"}

Equal spread leavesThe equal leaves spreading method distributes a specified value equally across all leaves of aconsolidated cell. When you apply this method, you can choose to distribute the value to all leaves of theconsolidation or only to those leaves that already contain non-zero values.

The spread code for equal spread leaves is LS. For more information, see “Spreading command codes” onpage 156.

Example

This example spreads 200 to all leaves in the current consolidation.

POST api/v1/Cellsets('AAAAAA')/tm1.Update{ "BeginOrdinal":0, "Value":"LS+*200"}

Applying holdsApplying and releasing holds on leaf cells and consolidations is done through the same actions you use tospread data.

The arguments you pass to these actions to apply or release holds are very similar. There are specialspreading commands for holding leaves and consolidations, and for releasing holds on leaves andconsolidations.

The spread code for a leaf hold function is H. The spread code for a consolidated hold function is HC. Formore information, see “Spreading command codes” on page 156.

Example

This example holds all leaf cells on the row of insertion.

POST api/v1/Cellsets('AAAAAA')/tm1.Update{ "BeginOrdinal":0, "Value":"H<>"}

Spreading command codesThe following table provides information about the spreading command codes.

Note:

1. The default data action is Replace. The spreading syntax uses the tilde character (~) to denote theSubtract data action, and the plus symbol (+) to denote the Add data action.

2. Straight Line and Growth % methods can be used across a single row or column. Rectangular rangesare not allowed. Direction combinations of up and down (^|) or left and right(<>) are the onlycombinations allowed for these spreading methods.

156 IBM Planning Analytics TM1 REST API

Data Spreading Method Code

Update Action

Direction Indicators

Required Method Parameters

Example

Proportional Spread P

+, ~

|, ^, <, >

Value to be spread

P<>100

This example proportionallyspreads the value 100 to all leafcells on the row of insertion,replacing existing cell values.

Equal Spread S

+, ~

|, ^, <, >

Value to be spread

S+|^200

This example equally spreads thevalue 200 to all leaf cells on thecolumn of insertion, adding theproduct of spreading to existingcell values.

Repeat R

+, ~

|, ^, <, >

Value to be spread

R~<50

This example subtracts the value50 from all leaf cells left of theinsertion point.

Percent Change P%

+, ~

|, ^, <, >

Percentage

P%+|^<>10

This example applies a percentchange of 10% to all leaf valuesin the view and adds the productto existing cell values.(Itincrements all leaves in the viewby 10%.)

Straight Line SL

+, ~

|, ^, <, > ∗∗Start Value and End Value

SL>100:200

This example applies StraightLine spreading to replace all leafvalues right of the point ofinsertion, using a start value of100 and an end value of 200.

Growth % GR

+, ~

|, ^, <, > ∗∗Start Value and GrowthPercentage

GR|300:25

This example applies a 25%growth percentage to the startingvalue of 300 and replaces all leafvalues below the point ofinsertion.

Clear C

N/A

|, ^, <, >

N/A

C|^<>

This example clears values fromall cells in the view.

Data spreading with the TM1 REST API 157

Data Spreading Method Code

Update Action

Direction Indicators

Required Method Parameters

Example

Relative Proportional Spread RP

+, ~

N/A

Value to be spread

RP+500

Distributes the value 500proportionally across all leaf cellsof the consolidation.

Relative Percent adjustment R%

+, ~

N/A

Percentage adjustment

R%+20

For each leaf cell in theconsolidation, take the value ofthe reference cell's analagousleaf cell, add 20%, and add thetotal to the leaf cell in the currentconsolidation.

Repeat Leaves LR

+, ~

The default is to updatepopulated cells.

* means update all leaf cells

Value to be spread

LR+*200

Add 200 to all populated leavesin the current consolidation.

Equal spread Leaves LS

+, ~

The default is to updatepopulated cells.

* means update all leaf cells

Value to be spread

LS+*200

Spread 200 to all leaves in thecurrent consolidation.

Leaf Hold H

N/A

|, ^, <, >

N/A

H<>

This example holds all leaf cellson the row of insertion.

Release Leaf Hold RH

N/A

|, ^, <, >

N/A

RH<>

This example releases all leafholds on the row of insertion.

158 IBM Planning Analytics TM1 REST API

Data Spreading Method Code

Update Action

Direction Indicators

Required Method Parameters

Example

Consolidation Hold HC

N/A

|, ^, <, >

N/A

HC<>

This example holds allconsolidated cells on the row ofinsertion.

Release Consolidation Hold RC

N/A

|, ^, <, >

N/A

RC<>

This example releases allconsolidated cells on the row ofinsertion.

Data spreading with the TM1 REST API 159

160 IBM Planning Analytics TM1 REST API

Chapter 7. TM1 settingsYou can use the Logger entity type and ServerSettings entity types to retrieve and update TM1 logfile settings.

Retrieve, update, and delete tm1s-log.properties file settings

The Logger entity type and the entity set /api/v1/Loggers represent the tm1s-log.propertiesfile. Each logger has a name, which corresponds with the logger name in the tm1s-log.properties file.For example, the logger named "TM1.API.Parameters" has the same name as a Logger entity. Eachlogger has a log level, which corresponds to the log levels that are set in the tm1s-log.properties file.

Loggers are all present in the entity set, even if they're not specified in tm1s-log.properties file. Toset the level, use a PATCH request on the logger:

PATCH /api/v1/Loggers('TM1.API.Parameters'){ "Level" : "Debug" }

You can use a DELETE request to remove a logger setting. The logger remains in the entity set. This isuseful if you want the logger setting to revert to inheriting its level from a parent logger. For example,TM1.API is a parent of TM1.API.Parameters.

Retrieve and update tm1s.cfg file settings

The ServerSettings entity type represents the tm1s.cfg file settings. The following types cover thepublicly documented tm1s.cfg file settings:

“AccessSettings” on page 62

• NetworkSettings• AuthenticationSettings• SSLSettings• CAMSettings• LDAPSettings• CAPISettings• HTTPSettings

“AdministrationSettings” on page 62

• ClientSettings• AuditLogSettings• DebugLogSettings• ServerLogSettings• EventLogSettings• JavaSettings• ExternalDatabaseSettings• TM1WebSettings

“ModellingSettings” on page 70

• SpreadingSettings• TISettings• RulesSettings• StartupSettings

© Copyright IBM Corp. 2007, 2019 161

• SynchronizationSettings

“PerformanceSettings” on page 71

• MemorySettings• MTQSettings• LockingSettings• ViewCalculationSettings• StargateSettings• JobQueuingSettings

The EDM schema has two root level instances of the ServerSettings entity type, /api/v1/ActiveConfiguration and /api/v1/StaticConfiguration.

ActiveConfiguration is read-only, and represents the current state of the server, not necessarily whatexists in the tm1s.cfg file. Many parameters are static and need a server restart for changes to takeeffect.

StaticConfiguration can be written with PATCH requests to modify the tm1s.cfg file. The PATCHrequest triggers a config refresh, and if the updated parameter is dynamic, ActiveConfiguration isupdated to reflect the change. StaticConfiguration always reflects what is in the tm1s.cfg file.

162 IBM Planning Analytics TM1 REST API

Chapter 8. TroubleshootingThe following section describes common troubleshooting scenarios and HTTP status codes.

HTTP status codes

The TM1 REST API uses standard HTTP/1.1 protocol to communicate between the client and the server.This means that requests and responses follow the conventions for this protocol, in addition to the rulesidentified by the OData specification. For specific details about the common response status codes andtheir meaning, see Section 9 of OData Version 4.0 Part 1: Protocol.

Response status codes from the server typically fall into one of the following categories:

• 2xx range typically indicates a successful operation• 3xx range identifies redirection while 304 is returned when the client issues a GET request and content

has not changed when using If-Match or If-None-Match• 4xx range is generally an error in the client request, such as a malformed request• 5xx status is likely an error on the part of the TM1 server

In addition to HTTP status codes, you might receive an error message from the TM1 server that identifiesmore details. For example, if you try to create an entity when an entity with the same name exists, theserver issues a 400 status code, and the following message in JSON format is included in the responsebody:

{"error":{"code":"","message":"A dimension named my_new_department2 already exists."}}

The error message can provide additional information to help you diagnose the error.

405 Method Not Allowed

Trying to perform an operation on an entity when the operation is invalid for that context results in a 405error from the server. In the response header, a list of valid operations is listed in an Allow header:

Status Code: 405Content-Type: text/plainContent-Length: 0Connection: keep-aliveAllow: GET, POST, PATCH, DELETE, OPTIONSOData-Version: 4.0

In this example, only GET, POST, PATCH, DELETE, or OPTIONS is allowed on the entity that is specified inthe request.

Monitoring HTTP traffic on the client or server

To help you troubleshoot issues, you can use several tools to debug your issue. HTTP traffic monitoringtools, and REST or web development plug-ins for common web browsers can provide extra details aboutthe requests and responses between the client and server that can help you troubleshoot.

It might also be possible to configure an HTTP monitoring tool as a proxy on the server to monitor alltraffic.

Invalid JSON payload (400)

If you include JSON content in a POST request, you receive an error from the server if the payloadcontains invalid JSON syntax:

{"error":{"code":"","message":"Invalid JSON:"}}

Use a validation tool to ensure that your JSON payload is correctly formatted before you submit a request.

© Copyright IBM Corp. 2007, 2019 163

For more information, use the following resources:

• “Conformance” on page 1• Common Response Status Codes

164 IBM Planning Analytics TM1 REST API

Chapter 9. Appendix 1: TM1 Admin HostThe TM1 Admin Server uses port 5895 for HTTP or port 5898 for HTTPS to communicate with the TM1REST API. These values cannot be changed 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:

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

Where [xxxx] is an available port number.

Restart the TM1 Admin Server and verify the port number settings by specifying http://tm1server:8000/api/v1/Servers in a local browser instance.

The response identifies the available servers in the following form:

{"@odata.context": "$metadata#Servers", "value": [ { "Name": "Planning Sample", "IPAddress": "9.26.42.237", "IPv6Address": "", "PortNumber": 12347, "ClientMessagePortNumber": 0, "HTTPPortNumber": 8000, "UsingSSL": false, "AcceptingClients": true } ]}

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

© Copyright IBM Corp. 2007, 2019 165

166 IBM Planning Analytics TM1 REST API

Chapter 10. Notices

This information was developed for products and services offered worldwide.

This material may be available from IBM in other languages. However, you may be required to own a copyof the product or product version in that language in order to access it.

IBM may not offer the products, services, or features discussed in this document in other countries.Consult your local IBM representative for information on the products and services currently available inyour area. Any reference to an IBM product, program, or service is not intended to state or imply that onlythat IBM product, program, or service may be used. Any functionally equivalent product, program, orservice that does not infringe any IBM intellectual property right may be used instead. However, it is theuser's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.This document may describe products, services, or features that are not included in the Program orlicense entitlement that you have purchased.

IBM may have patents or pending patent applications covering subject matter described in this document.The furnishing of this document does not grant you any license to these patents. You can send licenseinquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual PropertyDepartment in your country or send inquiries, in writing, to:

Intellectual Property LicensingLegal and Intellectual Property LawIBM Japan Ltd.19-21, Nihonbashi-Hakozakicho, Chuo-kuTokyo 103-8510, Japan

The following paragraph does not apply to the United Kingdom or any other country where suchprovisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATIONPROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS ORIMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer ofexpress or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodicallymade to the information herein; these changes will be incorporated in new editions of the publication.IBM may make improvements and/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not inany manner serve as an endorsement of those Web sites. The materials at those Web sites are not part ofthe materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate withoutincurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) theexchange of information between independently created programs and other programs (including thisone) and (ii) the mutual use of the information which has been exchanged, should contact:

IBM Software GroupAttention: Licensing

© Copyright IBM Corp. 2007, 2019 167

3755 Riverside Dr.Ottawa, ONK1V 1B7Canada

Such information may be available, subject to appropriate terms and conditions, including in some cases,payment of a fee.

The licensed program described in this document and all licensed material available for it are provided byIBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or anyequivalent agreement between us.

Any performance data contained herein was determined in a controlled environment. Therefore, theresults obtained in other operating environments may vary significantly. Some measurements may havebeen made on development-level systems and there is no guarantee that these measurements will be thesame on generally available systems. Furthermore, some measurements may have been estimatedthrough extrapolation. Actual results may vary. Users of this document should verify the applicable datafor their specific environment.

Information concerning non-IBM products was obtained from the suppliers of those products, theirpublished announcements or other publicly available sources. IBM has not tested those products andcannot confirm the accuracy of performance, compatibility or any other claims related to non-IBMproducts. Questions on the capabilities of non-IBM products should be addressed to the suppliers ofthose products.

All statements regarding IBM's future direction or intent are subject to change or withdrawal withoutnotice, and represent goals and objectives only.

This information is for planning purposes only. The information here is subject to change before theproducts described become available.

This information contains examples of data and reports used in daily business operations. To illustratethem as completely as possible, the examples include the names of individuals, companies, brands, andproducts. All of these names are fictitious and any similarity to the names and addresses used by anactual business enterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, which illustrate programmingtechniques on various operating platforms. You may copy, modify, and distribute these sample programsin any form without payment to IBM, for the purposes of developing, using, marketing or distributingapplication programs conforming to the application programming interface for the operating platform forwhich the sample programs are written. These examples have not been thoroughly tested under allconditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of theseprograms. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not beliable for any damages arising out of your use of the sample programs.

Each copy or any portion of these sample programs or any derivative work, must include a copyrightnotice as follows:© (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. ©Copyright IBM Corp. _enter the year or years_.

If you are viewing this information softcopy, the photographs and color illustrations may not appear.

This Software Offering does not use cookies or other technologies to collect personally identifiableinformation.

©

168 IBM Planning Analytics TM1 REST API

Product Information

This document applies to IBM Planning Analytics 2.0.0 and may also apply to subsequent releases.

Copyright

Licensed Materials - Property of IBM© Copyright IBM Corp. 2007, 2019.

US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP ScheduleContract with IBM Corp.

IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International BusinessMachines Corp., registered in many jurisdictions worldwide. Other product and service names might betrademarks of IBM or other companies. A current list of IBM trademarks is available on the web in "Copyright and trademark information " at www.ibm.com/legal/copytrade.shtml.

The following terms are trademarks or registered trademarks of other companies:

• Microsoft, Windows, Windows Server, and the Windows logo are trademarks of Microsoft Corporation inthe United States, other countries, or both.

• Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks ortrademarks of Adobe Systems Incorporated in the United States, and/or other countries.

• Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.• UNIX is a registered trademark of The Open Group in the United States and other countries.• Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or

its affiliates.

Microsoft product screen shot(s) used with permission from Microsoft.

Notices 169

170 IBM Planning Analytics TM1 REST API

IBM®