TM1 Source Specification

A regular TM1 object is a kind of server object that can be described using a set of attributes, namely properties. The source of such object is a JSON object that contains the properties and the values of the properties. The JSON object is saved in a text file. The name of the file SHOULD be the name of the object. The extension of the file SHOULD be json.

Example 1: The source of a Cube in fileCube_A.json

{
  "Name": "Cube_A",
  "Dimensions":
  [
    { "@id": "Dimensions('Dimension_A')" },
    { "@id": "Dimensions('Dimension_B')" }
  ]
}

A collection object is a collection of TM1 objects of the same type. The source of a collection object is a JSON object that MUST be annotated with the object type, and MUST contain a value property that defines a TM1 object array. The JSON object is saved in a text file. The name of the file SHOULD have three parts, which are separated with the dot(.) character. The first part SHOULD be the name of the containing object, the second part SHOULD be the type name of the collection in lowercase, and last part SHOULD be a json extension.

Example 2: The source of a Hierarchies collection in file Dimension_A.hierarchies.json

{
  "@type": "Collection(Hierarchy)",
  "value":
  [
    {
      "Name": "Hierarchy_A",
      "Elements":
      [
        { "Name": "Element_A" },
        { "Name": "Element_B" }
      ]
    }
  ]
}

Objects and property values can be linked to another file with the @Code.link annotation as oppose to being defined inline. The @Code.link annotated value is a link pointing to a file that contains the source of an object, or the raw value of a property. The file is RECOMMENDED to have a specific extension that indicates the syntax of the content. For example, Cube Rules are RECOMMENDED to be linked to files with rules extension, TI Code is RECOMMENDED to be linked to files with ti extension.

The file content of a linked primitive property MUST contain the raw value only. Control characters MUST NOT be escaped.

The file content of a linked object MUST be a JSON object. The file extension SHOULD be json.

Other than using "@Code.link" to link to a file, a collection object is RECOMMENDED to use the @Code.links annotation to specify an array of links, each of which defines a link to an object in the collection.

Example 3: The source of a Process, with the Code of the Process linked, in file Process_A.json and Process_A.ti respectively.

{
  "Name": "Process_A",
  "Code@Code.link": "Process_A.ti"
}

#region prolog
#endregion

Example 4: The links of Dimension_A's Hierarchies

{
  "Name":"Dimension_A",
  "Hierarchies@Code.links":
  [
    "Dimension_A.hierarchies/A.json",
    "Dimension_A.hierarchies/B.json"
  ]
}

The source of a binary file is the file itself. The Application files generated by the server are the sources of the Applications.

Action GitInit binds a remote Git repository to the TM1 server. It also initializes a Git context that stores the information of the Git-related operations, for example, the most recent Git branch that has been deployed. The Git context is persistent and server-scoped.

GitInit takes the following parameters:

• URL: the URL of the Git repository. When present, the URL MUST match the URL in the Git context, if the Git context is not being reset.

• Deployment: the selected deployment.

• Username: the Git credential.

• Password: the Git credential.

• PublicKey: the SSH public key.

• PrivateKey: the SSH private key paired with the SSH public key.

• Passphrase: the passphrase for decrypting the SSH private key. When none of the credentials is specified, the server does not verify the connection to the Git. Otherwise, the connection must be valid. The credentials will be cached in the HTTP session.

• Force: whether to reset the Git context.

• Config: the Git configuration parameters. The configuration parameter http.proxy specifies the URL of the HTTP proxy via which the server can connect to the Git repository when the repository is on HTTPS.

If GitInit succeeded, the server updates the Git context with the new URL and Deployment, invalidates all the pending Git pull plans and Git push plans, and returns the status of the local Git context and the information of the Git server.

Example 6: Initialize Git to a repo at github.com

POST /api/v1/GitInit
{
  "URL": "https://github.com/tm1models/model.git",
  "Deployment": "dev",
  "Username": "username",
  "Password": "password",
  "Force": true,
  "Config":
  {
    "http.proxy": "http://localhost:8888/"
  }
}

Example 7: Initialize Git to a local bare repo

POST /api/v1/GitInit
{
  "URL": "file:///c:/model.git",
  "Deployment": "prod",
  "Force": false
}

Action GitUninit frees the memory allocated for Git, deletes the Git temporary folder, and disables all Git-related functions except GitInit.

GitUninit takes the following parameters:

• Force: whether to clean up Git context.

Action GitStatus returns the Git context and the information of the Git server. The action also initializes Git if it is not initialized.

GitStatus takes the following parameters:

• Username: the Git credential.

• Password: the Git credential.

• PublicKey: the SSH public key.

• PrivateKey: the SSH private key paired with the SSH public key.

• Passphrase: the passphrase for decrypting the SSH private key.

The first step to deploy a model is to execute the GitPull action to create a Git pull plan.

GitPull takes the following parameters:

• Branch: the name of the branch or tag to fetch source from.

• ExecutionMode: indicates whether to commit right after each operation performed during deploying the model, or to commit after all operations are done.

• Force: a flag passed in for evaluating preconditions.

• Username: the Git credential.

• Password: the Git credential.

• PublicKey: the SSH public key.

• PrivateKey: the SSH private key paired with the SSH public key.

• Passphrase: the passphrase for decrypting the SSH private key.

If the Git server is valid, the TM1 server fetches the last commit of the specified branch or tag. From the commit, the server reads and validates the tm1project file and the sources, and creates a GitPullPlan object. The GitPullPlan dynamically determines the actions to be done to deploy the source, based on the Git context, the hash of the source as stored in the Git context (i.e. updated on last push), and the hash of the server object. An action could be to create an object, to execute a TI or to set configurations, etc.

A GitPullPlan is bound to a specific Git commit. It is session-scoped, and can be addressed in the GitPlans entity set.

The second step to deploy a model is to execute the Execute action against the GitPullPlan. The server performs the actions required by the plan. If all the actions succeeded, the server updates Git context with the information gathered during the deployment. The Git context will be further used to determine what is the action to do for a certain object in the future deployment. It is also used to determine how to format the sources.

A GitPullPlan is deleted after a successful execution. It can be deleted explicitly from the GitPlans entity set.

Example 8: Deploy a model by using the action GitPull and Execute

POST /api/v1/GitPull
{
  "Branch": "CompanyModel",
  "ExecutionMode": "SingleCommit",
  "Force": true,
  "PublicKey": "public key",
  "PrivateKey": "private key",
  "Passphrase": "passphrase"
}

POST /api/v1/GitPlans('GIT_PLAN_ID')/tm1.Execute

The first step to publish a model is to execute the GitPush action to create a Git push plan.

GitPush takes the following parameters:

• Branch: the branch from which the last commit is used as the parent commit of the commit to create. If the Git repository is empty, this parameter MUST NOT be specified.

• NewBranch: if specified, the server creates a new branch and push the new commit onto it; if not specified, the server pushes the new commit onto the branch specified by Branch. If the Git repository is empty, this parameter MUST be present to instruct the server to create a base commit.

• Force: a flag passed in for evaluating preconditions.

• Message: the commit message.

• Author: the name of the commit author.

• Email: the email of the commit author.

• Username: the Git credential.

• Password: the Git credential.

• PublicKey: the SSH public key.

• PrivateKey: the SSH private key paired with the SSH public key.

• Passphrase: the passphrase for decrypting the SSH private key.

If the Git repository is valid, the TM1 server generates the sources of the server objects, creates a commit using the source files and sets the parent of the commit to the last commit of the branch specified in Branch. With the new commit, the server creates a GitPushPlan object.

The server generates the source of the Cubes, Dimensions, Processes, and Chores. The server does not generate the source of the private or control objects unless explicitly specified. The server formats the source based on the format information in the Git context.

A GitPushPlan is bound to a specific Git commit. It is session-scoped, and can be addressed in the GitPlans entity set.

The second step to publish a model is to execute the Execute action against the GitPushPlan object. The server pushes the commit to Git.

A GitPushPlan is deleted after a successful push. It can be deleted explicitly from the GitPlans entity set.

Example 9: Publish the changes to the model CompanyModel

POST /api/v1/GitPush
{
  "Branch": "CompanyModel",
  "Force": true,
  "Message": "Added some cubes",
  "author": "TM1 designer",
  "Email": "tm1designer@ibm.com",
  "Username": "username",
  "Password": "password"
}

POST /api/v1/GitPlans('GIT_PLAN_ID')/tm1.Execute

Action GitDeploy initializes Git, deploys a model, updates the Git context, and terminates Git.

GitDeploy takes the following parameters:

• URL: the URL of the remote Git repository.

• Deployment: the selected deployment.

• Branch: the name of the branch or tag to fetch.

• Force: a flag passed in for evaluating preconditions.

• Username: the Git credential.

• Password: the Git credential.

• PublicKey: the SSH public key.

• PrivateKey: the SSH private key paired with the SSH public key.

• Passphrase: the passphrase for decrypting the SSH private key.

The action does not clean up the Git context.

Resource !tm1project enables viewing and modifying the tm1project file (see TM1 Project for more details).

The server uses the following schemes to name objects, link files, and folders:

• Use an object’s name (key) as the file name of the source, use json as the extension.

• Store root level server objects in folders named after the type of the object in lowercase. Root level server objects include Cubes, Dimensions, Processes, and Chores.

• Store-specific collection objects in folders named after the name of the containing object followed by a dot followed by the type of the collection objects in lowercase. The collection objects include Dimension Hierarchies, Hierarchy Subsets, and Cube Views.

• Link-specific object properties. The file name is the name (key) containing object. The extension is the type of the property in lowercase. The properties include Cube Rules, MDXView MDX, and Process Code.

• The schemes can be overridden when specified.

Example 10: Source filenames

/cubes/Cube_A.json
/cubes/Cube_A.rules
/cubes/Cube_A.views/View_A.json
/cubes/Cube_A.views/View_B.json
/dimensions/Dimension_A.json
/dimensions/Dimension_A.hierarchies/Dimension_A.json
/dimensions/Dimension_A.hierarchies/Dimension_A.subsets/Subset_A.json
/processes/Process_A.json
/processes/Process_A.ti

A project file tm1project.json SHOULD be created for each model. It specifies how to deploy and publish the model. The content of the project file is a JSON object with properties explained in the following sections.

The project file can be manually modified on Git. The server exposes the project file as a !tm1project resource, which can be viewed (GET) and modified (PUT). The project file is a part of the Git context. When a model is successfully deployed, the project file in the deployed model becomes the project file of the server.

When a tm1project file is not present, the server loads the sources from all the default locations.

A README.md file can be put into the source. If exists, the file will be added into any new commit without any modification. There is no interface for editing the file on the TM1 server side.

In the following description, if a field is not explicitly REQUIRED or described with a MUST, it can be considered OPTIONAL.

{
    "$Version": "4.0",
    "$Reference": {
        "https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.json": {
            "$Include": [
                {
                    "$Alias": "Core",
                    "$Namespace": "Org.OData.Core.V1"
                }
            ]
        }
    },
    "ibm.tm1.code.v1": {
        "$Kind": "Schema",
        "$Alias": "Code",
        "@Core.Description": "Describes terms to augment your TM1 model 'source' for consumption by TM1 Server and other, aware, tools",
        "Link": {
            "$Kind": "Term",
            "@Core.Description": "A path to the file containing the actual 'source' for the annotated element, relative to the location of the 'source' it is used within"
        },
        "Links": {
            "$Kind": "Term",
            "$Collection": true,
            "@Core.Description": "A path to the file containing the actual 'source' for the annotated collection valued element, relative to the location of the 'source' it is used within"
        }
    }
}

{
    "$Version": "4.0",
    "$Reference": {
        "https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Core.V1.json": {
            "$Include": [
                {
                    "$Alias": "Core",
                    "$Namespace": "Org.OData.Core.V1"
                }
            ]
        }
    },
    "ibm.internal.tm1.source.v1": {
        "$Alias": "tm1Source",
        "@Core.Description": "IBM INTERNAL USE ONLY! Describes terms to augment a combined TM1, OData compliant, REST API and model source definition based on a common, OData compliant, CSDL specification",
        "Include": {
            "$Kind": "Term",
            "$Type": "Core.Tag",
            "$DefaultValue": true,
            "$AppliesTo": ["EntityType", "ComplexType", "TypeDefinition", "EnumType", "Property", "NavigationProperty"],
            "@Core.Description": "Indicates that the tagged element can be defined as part of the 'source' for a TM1 model"
        },
        "Only": {
            "$Kind": "Term",
            "$Type": "Core.Tag",
            "$DefaultValue": true,
            "$AppliesTo": ["EntityType", "ComplexType", "TypeDefinition", "EnumType", "Property", "NavigationProperty"],
            "@Core.Description": "Indicates that the tagged element can only be defined as  part of the 'source' for a TM1 model"
        },
        "Required": {
            "$Kind": "Term",
            "$Type": "Core.Tag",
            "$DefaultValue": true,
            "$AppliesTo": ["Property", "NavigationProperty"],
            "@Core.Description": "Indicates that the tagged element is required as part of the 'source' for the element it is contained within"
        },
        "Documentation": {
            "$Kind": "Term",
            "$Collection": true,
            "$Type": "tm1Source.ParagraphType",
            "$Nullable": false,
            "$AppliesTo": ["Schema", "EntityType", "ComplexType", "TypeDefinition", "EnumType"],
            "@Core.Description": "Associates additional documentation with the tagged element"
        },
        "ParagraphType": {
            "$Kind": "ComplexType",
            "@Core.Description": "One of potentially multiple paragraphs of documentation associated with an element describing the source for a TM1 model",
            "MarkDown": {
                "@Core.Description": "Documentation using the MarkDown format"
            },
            "CodeSnippets": {
                "$Collection": true,
                "$Type": "tm1Source.CodeSnippetType",
                "$Nullable": false,
                "@Core.Description": "A collection of zero or more code snippets associated with the paragraph"
            }
        },
        "CodeSnippetType": {
            "$Kind": "ComplexType",
            "@Core.Description": "The source 'code' for the example in the specified format",
            "Format": {
                "$Nullable": true,
                "$DefaultValue": "JSON",
                "@Core.Description": "The format or language of the code in this snippet (eg JSON)"
            },
            "Code": {
                "@Core.Description": "The actual 'code' for this snippet"
            }
        },
        "FileExtension": {
            "$Kind": "Term",
            "$DefaultValue": "json",
            "$AppliesTo": ["Property", "NavigationProperty"],
            "@Core.Description": "The file extension expected to be used for files referenced, using a Code.Link annotation, to describe the value for this property"
        }
    }
}