Add or Update Calculated Measures

Content-Type (Required)

String

Specifies the media type of the request body.

application/x-www-form-urlencoded

sessionid

String

The session ID is the token received from the login API.

Note: Session ID is required for token-based authentication.

–

name-or-id (Required)

String

Name or ID of the Workbook in which calculated measures need to be added or updated.

Note: If the Workbook name is provided, then either folderName or folderId must also be provided.

–

by

String

Specifies whether the name-or-id parameter should be interpreted as a Workbook name or Workbook ID.

If by=name, provide the Workbook name in the name-or-id parameter.

If by=id, provide the Workbook ID in the name-or-id parameter.

The default value is name.

–

folderName

String

Name of the folder containing the Workbook. If the Workbook is present in the root directory, specify [Root].

Note: If neither folderName nor folderId is provided, the Workbook will be treated as a root-level entity by default.

–

folderId

String

ID of the folder containing the Workbook.

–

measuresJson (Required)

String

A JSON string containing the name of the measure as the key and another JSON object containing the properties of the measure as the value.

Note: A sample JSON example is provided under the Resources section below.

–

401

Authorization information is missing or invalid.

404

No matching record found.

412

Precondition failed. Parameter missing.

500

Internal Server Error

Field

Type

Description 

Possible Values 

Example

measuresJson

string (JSON)

A JSON string containing one or more calculated measure definitions. Required. 

Valid JSON object.

"{\"Profit Margin\":{...}}"

measuresJson.<measureName>

object

The key is the calculated measure's display name. Required for each measure. 

JSON object.

{...}

measuresJson.<measureName>.expression

string

The formula used to calculate the measure. It is written in the semantic model's query language (usually MDX). Required. 

Any valid expression.

"[Measures].[Profit] / [Measures].[Sales]"

measuresJson.<measureName>.measureId

string

The unique ID to assign (for new) or identify (for update) the measure. If you use an ID that already exists in the same workbook or semantic model, the request is rejected. Optional. 

Any string.

"17774561929407127091090133193817"

measuresJson.<measureName>.description

string

A short human-readable explanation of what the measure represents. Optional. 

Any text.

"Profit divided by sales"

measuresJson.<measureName>.semanticModelId

string

The ID of the semantic model where the source measures live. Required if semanticModelName is not given. 

Any valid semantic model ID.

"17748606041027127091090133193817"

measuresJson.<measureName>.semanticModelName

string

The name of the semantic model where the source measures live. Required if semanticModelId is not given. 

Any valid semantic model name.

"AdventureWorks"

measuresJson.<measureName>.semanticModelFolderName

string

The folder containing the semantic model. Optional, but recommended when the name is not unique. 

Any folder name.

"Kyvos_NoSpark"

measuresJson.<measureName>.groupName

string

The name of the measure group the calculated measure should be placed in. Required for a new measure; Optional when updating. 

Any group name.

"Financial Ratios"

measuresJson.<measureName>.groupDescription

string

A description for the measure group (only used when the group is created). Optional. 

Any text.

"KPIs and ratios"

measuresJson.<measureName>.solveOrder

string

The order in which this measure is evaluated when multiple calculated measures exist. Lower numbers are evaluated first. If not set, it defaults to 0. Optional.

Any numeric string.

"10"

measuresJson.<measureName>.formatType

string

The kind of formatting to apply to the displayed value. Optional.

1 = Text, 2 = Number (custom), 3 = Currency, 4 = Date, 5 = Time, 6 = Percentage, 7 = Scientific, 8 = Network ID, 9 = Custom, 10 = Duration. Defaults to 2.

"2"

measuresJson.<measureName>.format

string

The display format string for the value. Optional. 

Any valid format string. Defaults to "#,##0.00".

"#,##0.00%"

measuresJson.<measureName>.isVisible

boolean

Whether the measure is visible to users. Optional.

true (default), false

TRUE

measuresJson.<measureName>.nonEmptyBehaviour

string

How the system should treat empty or zero values. BY_EXPRESSION means the expression's own result decides. BY_MEASURE means another base measure is checked for non-empty values before calculating. Optional. 

BY_EXPRESSION (default), BY_MEASURE

"BY_MEASURE"

measuresJson.<measureName>.nonEmptyMeasures

string

A comma-separated list of base measures to check for non-empty values. Required when nonEmptyBehaviour = BY_MEASURE. 

Measure names or IDs (see next field).

"Sales,Profit"

measuresJson.<measureName>.nonEmptyMeasuresContainsMeasureIds

boolean

Tells the system whether nonEmptyMeasures is a list of measure IDs (true) or measure names (false). Optional.

true, false (default)

FALSE

measuresJson.<measureName>.hasParameterInExpression

boolean

Set to true if the measure's expression contains a dashboard/worksheet parameter that also affects non-empty behaviour. Optional, used with BY_MEASURE. 

true, false (default)

FALSE