Attributes and localization

You can localize an IBM® TM1® Server by assigning locale-specific values to attributes that are associated with 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 Caption attribute must be added if it does not exist. This Caption attribute can be set up as a Text type or as an Alias type. When this attribute is of type Alias, TM1 enforces the uniqueness of its values, and you can use the Caption value to search for the associated TM1 object. When this Caption attribute is just a Text type, its values are for displaying locale-specific caption and cannot be used in searching for TM1 Objects.

TM1 Server uses international language codes that are defined by ISO 639-1 to identify major languages and the IETF language tag in assigning locale-specific value. For example, fr is for French and fr-FR is for French (France). When you assign a localized value to an attribute, it is only necessary to assign to the major language code, for example, for fr. TM1 Server automatically retrieves the value for the major language if it is asked for a specific locale such as fr-FR or fr-CA if values associated to those locales do not exist. By default, if no localized values are found for an attribute, the base default attribute value is returned.

Create Attributes and Captions for an entity

You can assign localized values to any attribute for all language locales, as elements in the }Cultures control dimension.

To change the set of locales, you can remove unused locales or add new ones. Make sure that you maintain any locales references as parent locales.

Follow these steps to add attributes and localized values that are associated with those attributes by using the TM1 REST API. In this example, the attributes and localized values are added to a cube, but the same steps apply to other entities as well.

Create a }CubeAttributes dimension and specify the set of attributes that are associated with cubes.
Although the Caption attribute is built in, it needs to physically exist only if you want to explicitly specify 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"
                }
            ]
        }
    ]
}
```

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')"
    ]
}

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"
    }
}

Execute a view or MDX query that returns a cellset that contains the cells and values for those attributes 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 ID value DWjRKwMCAIADAAAg. In your own procedure, use the ID property value that is returned in the Cellset in the response.

Locate cells that you want to update. In this example the Caption for the plan_BudgetPlan cube is set.

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"
        },
        ...

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')
```

To create the }LocalizedCubeAttributes cube, use the following request.

POST /api/v1/Cubes

{
    "Name": "}LocalizedCubeAttributes",
    "Dimensions@odata.bind": [
        "Dimensions('}Cubes')",
        "Dimensions('}Cultures')",
        "Dimensions('}CubeAttributes')"
    ]
}

The response displays the results of creating the new control cube. This control cube stores the localized 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"
    }
}

Execute a view or MDX query that returns a cellset that contains the cells or values for the attributes you want to update. In this example, all attributes for the plan_budgetPlanLineItem cube for the Dutch (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]"
   }

Update cells that contain the localized values for the attributes you want to update. The ID used in the example needs to be changed to a value in your own model. In this example, the Dutch caption for the plan_budgetPlanLineItem cube is updated.
```
PATCH /api/v1/Cellsets('DWjRKwMCAICHAAAg')/Cells

[
    {
        "Ordinal": 0,
        "Value": "Budget Kubus"
    }
]
```

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 and 8, you can execute a POST query to create a localized attribute if the locale ID exists. If the locale ID that you supply exists and is supported by TM1 Server but the attribute does not exist, the localized attribute is created using that locale ID and then the localized value is added. If the locale ID does not exist, an exception is thrown. The following example creates a localized attribute for the caption.

POST /api/v1/Cubes('plan_BudgetPlan')/LocalizedAttributes

{
    "LocaleID":"en",
    "Attributes":
    {
        "Caption": "Budget Plan"
    }
}

Use TurboIntegrator functions

You 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 Caption attribute 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 lock contention, you should review your existing TurboIntegrator processes to use temporary Views and Subsets 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 in value 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 the optional language code as a parameter. Using the Caption attribute as an example, you can use the following 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 value is returned for other views. In addition, in the view caption case, if there are no attribute values defined in the 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] )

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 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 using the optional language code as a parameter. Using the Caption attribute as an example, you can use the following 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 default value is returned for other subsets. In addition, in the subset caption case, if there are no attribute values defined 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] )

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 that process.

Note: You use this function only for the process where a localized attribute value is desired. The default value is returned for other processes. In addition, in the process caption case, if there are no attribute values defined in the base attribute, the initial design invariant name is returned.

More information

For 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