Functions and actions

The 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 can be performed against the model. All functions and actions are defined according to the rules that are defined in OData Version 4 for custom operation. For more information, see Metadata.

Functions in OData (edm:Function) are operations that do not have any observable side effects and must return a single or multiple instances of a type that is specified by the functions edm:ReturnType element. 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 entity model and might return a value if an edm:ReturnType element is defined for the action. For more information about TM1 actions, see Actions.

Each <Action> and <Function> element contains an IsBound attribute for which the default value is false. If an action or function is defined as IsBound=true, the operation can be invoked only on the first element defined as a parameter for that operation. For example, the Execute action is bound to a View 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"/>
   <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 same as overloading in many programming languages, and indicates that this action can be invoked against either 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 OData specification.

In the previous example, because the action is bound to the View entity, it can be invoked only in that context:

/api/v1/Cubes('MyCube')/Views('MyView')/tm1.Execute

An operation that is imported into the API entity container (<EntityContainer Name="API">) is unbound and can be addressed at the root level, but only on the type of entity set that is defined for that action. In the following example, the ExecuteMDX action can be invoked only on the Cellsets entity type:

<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 of the 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