Updates a CustomCalculation for a Group.

CustomCalculations

---

CustomCalculation is a type of Group property which contains a formula. CustomCalculation defines a column in the output data that gets filled with the formula evaluation result. The formula is evaluated for each row of the Group's query result during each extraction.

The formula supports using other columns (GroupProperty, CalculatedProperty or CustomCalculation entities) as variables. Recursive formulas are not supported, i.e., formula containing a variable X is not supported inside a CustomCalculation with a propertyName equal to X.

Supported data types:

• Number - describes a real number. When converted to a boolean value in logical operators 0 becomes false and all other values become true
• Boolean - describes a logical value which is either true or false. When converted to a number in certain operators true becomes 1 and false becomes 0
• String - describes text. When converted to a boolean value in logical operators an empty string becomes false and all other strings become true

All of the supported data types can have no value which means that the value is null. Some operations support null values but those which do not will return null as the result.

Supported operators:

Parenthesis ( and ) can be used to change the precedence of operations. Variables, constants, and functions have a precedence of 1 and left associativity.

Supported constants:

• E - Euler's constant and the base of natural logarithms (approx. 2.718)
• LN2 - natural logarithm of 2 (approx. 0.693)
• LN10 - natural logarithm of 10 (approx. 2.303)
• LOG2E - base-2 logarithm of E (approx. 1.443)
• PI - ratio of a circle's circumference to its diameter (approx. 3.14159)
• SQRT1_2 - square root of ½ (approx. 0.707)
• SQRT2 - square root of 2 (approx. 1.414)

Supported numeric constant formats:

• Decimal, e.g., 123 or 1.123
• Binary (base 2), e.g., 0b1010
• Octal (base 8), e.g., 0o1234567
• Hexadecimal (base 16), e.g., 0x123af
• Scientific notation, e.g., 1.123e+3

Supported string literal formats:

• Single quotation marks, e.g., 'Column'
• Double quotation marks, e.g., "Column"
• Backticks, e.g., `Column`

Supported boolean formats:

• True, e.g., true
• False, e.g., false

Supported null format:

• Null, e.g., null

An escape character \ can be used to escape special characters in string literals. Supported escape sequences:

• \' - single quotation mark
• \" - double quotation mark
• \` - backtick
• \\ - backslash
• \n - newline character
• \t - tab character

If an unsupported escape sequence is found, then the escape character is dropped, e.g., \d becomes d.

Supported numerical functions:

• abs(x) - returns the absolute value of x
• acos(x) - returns the arccosine of x
• acosh(x) - returns the hyperbolic arccosine of x
• asin(x) - returns the arcsine of x
• asinh(x) - returns the hyperbolic arcsine of x
• atan(x) - returns the arctangent of x
• atanh(x) - returns the hyperbolic arctangent of x
• atan2(y, x) - returns the arctangent of the quotient of y divided by x
• cbrt(x) - returns the cube root of x
• ceil(x) - returns the smallest integer greater than or equal to x
• clz32(x) - returns the number of leading zero bits of the 32-bit integer x
• cos(x) - returns the cosine of x
• cosh(x) - returns the hyperbolic cosine of x
• exp(x) - returns E ** x or pow(E, x), where x is the argument, and E is Euler's constant (2.718…, the base of the natural logarithm)
• expm1(x) - returns subtracting 1 from exp(x)
• floor(x) - returns the largest integer less than or equal to x
• fround(x) - returns the nearest single precision float representation of x
• hypot(x, y[, z[, …]]) - returns the square root of the sum of squares of its arguments
• imul(x, y) - returns the result of the 32-bit integer multiplication of x and y
• log(x) - returns the natural logarithm of x
• log1p(x) - returns the natural logarithm of 1 + x
• log10(x) - returns the base-10 logarithm of x
• log2(x) - returns the base-2 logarithm of x
• max(x, y[, z[, …]]) - returns the largest of 2 or more numbers
• min(x, y[, z[, …]]) - returns the smallest of 2 or more numbers
• pow(x, y) - returns base x to the exponent power y (i.e., x**y)
• random() - returns a pseudo-random number between 0 and 1. The value only changes between different output tables. All rows within a single output table get the same value
• round(x) - returns the value of the number x rounded to the nearest integer
• sign(x) - returns the sign of the x, indicating whether x is positive (1), negative (-1), or zero (0)
• sin(x) - returns the sine of x
• sinh(x) - returns the hyperbolic sine of x
• sqrt(x) - returns the positive square root of x
• tan(x) - returns the tangent of x
• tanh(x) - returns the hyperbolic tangent of x
• trunc(x) - returns the integer portion of x, removing any fractional digits
• tonumber(var) - returns the var value converted to a number

Supported string functions:

• charat(str, index) - returns exactly one character at the specified index. Accepts negative integers, which count back from the last string character
• concat(str , ...strN) - combines the text of two (or more) strings and returns a new string
• padend(str, targetLength [, padString]) - pads the given string from the end with a given string and returns a new string of the length targetLength. Maximum value of targetLength is 100. The resulting string will be truncated if it is too long to stay within targetLength. The default value for padString is " " (white space)
• padstart(str, targetLength [, padString]) - pads the given string from the start with a given string and returns a new string of the length targetLength. Maximum value of targetLength is 100. The resulting string will be truncated if it is too long to stay within targetLength. The default value for padString is " " (white space)
• substring(str, beginIndex [, endIndex]) - returns a new string containing characters of str from (or between) the specified index (or indices)
• indexof(str, searchValue [, start]) - returns the index of the first occurance in str at which a given string searchValue can be found in the array, or -1 if it is not present.
• tolowercase(str) - returns the str value converted to lowercase
• touppercase(str) - returns the str value converted to uppercase
• trim(str) - trims whitespace from the beginning and end of str
• trimstart(str) - trims whitespace from beginning of str
• trimend(str) - trims whitespace from end of str
• tostring(var) - returns the var value converted to a string

Supported boolean functions:

• isin(var, var1[, var2[, ...]]) - returns true if var is equal to one of var1, ...varN else it returns false. var, ...varN must be of same type
• toboolean(var) - returns the var value converted to a boolean

Supported conditional functions:

• if(cond, expr_true, expr_false) - returns expr_true if cond is true else it returns expr_false. expr_true and expr_false must be of the same type. expr_true and expr_false can be null
• ifnull(var, expr) - returns expr if var is null else it returns var. var and expr must be of the same type. var can be null
• ifnotnull(var, expr) - returns expr if var is not null else it returns var. var and expr must be of the same type. var can be null
• ifempty(str, expr) - returns expr if str is empty else it returns str. str and expr must be strings
• ifnotempty(str, expr) - returns expr if str is not empty else it returns str. str and expr must be strings
• ifnullorempty(str, expr) - returns expr if str is null or empty else it returns str. str and expr must be strings. str can be null
• ifnotnullorempty(str, expr) - returns expr if str is not null and not empty else it returns str. str and expr must be strings. str can be null
• ifnullorwhitespace(str, expr) - returns expr if str is null or empty or only consists of whitespace else it returns str. str and expr must be strings. str can be null
• ifnotnullorwhitespace(str, expr) - returns expr if str is not null and not empty and not only consists of whitespace else it returns str. str and expr must be strings. str can be null

Supported unit functions:

• getpersistenceunit(var) - returns persistence unit of the provided argument as a String. Provided argument must be a GroupProperty that is mapped from an ECProperty and has data type set to Double. Example value: Units.M. More information about units can be found here
• getpresentationunits(var) - returns serialized json array of presentation units of the provided argument as a String. Provided argument must be a GroupProperty that is mapped from an ECProperty and has data type set to Double. Example value: [\"Units.M\",\"Units.FT\"]. More information about units can be found here

Examples of supported formulas:

• min(A * B, B * C, A * C) - if A, B, and C are 3 different lengths of box edges, then this formula will result in the smallest side surface area of that box
• min * max - formula does not have parenthesis after function names, so the min and max operands are treated as variables (other columns), not as functions. If the Group has columns min and max, and their values are 2 and 5, then the result of this formula is 10 for that row
• 2 ** 3 - 2 raised to the power of 3. Result will be 8. This can also be written as pow(2, 3)
• min(cos(X), sin(X)) - function nesting is supported
• A * (B + C) - A multiplied by the sum of B and C
• A * B + C - same as (A * B) + C
• padend(concat(A, '\\', touppercase(substring(B, 4))), C, D) - the result of concat, which concatenates variable A, string literal \ and uppercase substring of variable B from index 4, is padded in the end with the target length of C with a pad string of variable D
• charat(trim(A), B) - gets the character of a trimmed string variable A that is at index B
• if(A > B, A, B) - if A is greater than B then the result is A else it is B
• ifnullorempty(A, 'B = ') + B - if variable A is null or empty then the result of ifnullorempty function is the string literal B = else it is variable A. Then the final formula result is the addition of the result of ifnullorempty function and variable B
• if(A != null && B != null, A + B, 0) - if A is not null and B is not null then the result is the addition of A and B else it is 0

Authentication

---

Requires Authorization header with valid Bearer token for scope itwin-platform.

For more documentation on authorization and how to get access token visit OAUTH2 Authorization page.

Authorization

---

User must have imodels_write permission(s) assigned at the Project level. iModel specific permissions may also be applied at the iModel level if iModel level permissions are enabled.

Alternatively the user should be an Organization Administrator for the Organization that owns a given Project or iModel.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities Licensing, Cloud, and Web Services wiki page.

Rate limits

---

All iTwin Platform API operations have a rate limit. For more documentation on that visit Rate limits and quotas page.

"Try it out" Limitations

---

When you run an Extraction with the "Try it out" function on a Mapping that was created or modified by using the "Try it out" function, you are limited to 100 extracted rows for each group. Mapping modification is any POST/DELETE/PATCH/PUT request to any endpoint with the tag "Mappings" or if the URL contains {mappingId}.

{
    "propertyName": "UpdatedVolume",
    "formula": "Length * Width * Height",
    "quantityType": "Volume"
}

{
    "customCalculation": {
        "id": "1ba1f4dd-efc1-4bd1-86f0-a69a4f0d4743",
        "propertyName": "CalculatedPrice",
        "formula": "CalculatedVolume * 3.123",
        "dataType": "Number",
        "quantityType": "Monetary",
        "_links": {
            "imodel": {
                "href": "https://api.bentley.com/imodels/70a3d6d3-5385-4bc3-87c4-b6bf106e1c0a"
            },
            "mapping": {
                "href": "https://api.bentley.com/insights/reporting/datasources/imodels/70a3d6d3-5385-4bc3-87c4-b6bf106e1c0a/mappings/f1fe5959-35ab-467e-83b8-a679b722d80f"
            },
            "group": {
                "href": "https://api.bentley.com/insights/reporting/datasources/imodels/70a3d6d3-5385-4bc3-87c4-b6bf106e1c0a/mappings/f1fe5959-35ab-467e-83b8-a679b722d80f/groups/1d9ae44a-2204-4bf6-8397-5c590e04ba3e"
            }
        }
    }
}

{
    "error": {
        "code": "HeaderNotFound",
        "message": "Header Authorization was not found in the request. Access denied."
    }
}

{
    "error": {
        "code": "CustomCalculationNotFound",
        "message": "Requested CustomCalculation is not available.",
        "target": "customCalculationId"
    }
}

{
    "error": {
        "code": "CustomCalculationExists",
        "message": "CustomCalculation with this 'propertyName' already exists."
    }
}

{
    "error": {
        "code": "InvalidInsightsRequest",
        "message": "Error message."
    }
}

{
    "error": {
        "code": "TooManyRequests",
        "message": "More requests were received than the subscription rate-limit allows."
    }
}

{
    "title": "CustomCalculation",
    "type": "object",
    "description": "Defines a CustomCalculation or 'column' for a Group. It is calculated using the given formula for each element returned by the Group's query.",
    "properties": {
        "id": {
            "type": "string",
            "description": "The CustomCalculation Id."
        },
        "propertyName": {
            "type": "string",
            "description": "Name of the Property (OData v4 SimpleIdentifier)."
        },
        "dataType": {
            "type": "string",
            "description": "The data type of the GroupProperty. One of 'Boolean', 'Double', 'Number', 'String', or 'Undefined'."
        },
        "formula": {
            "type": "string",
            "description": "A mathematical formula which will be evaluated for each element returned by the Group's query."
        },
        "quantityType": {
            "type": "string",
            "description": "The quantity type of the CustomCalculation. One of 'Area', 'Distance', 'Force', 'Mass', 'Monetary', 'Time', 'Volume, or 'Undefined'."
        },
        "_links": {
            "type": "object",
            "properties": {
                "imodel": {
                    "$ref": "#/components/schemas/Link",
                    "description": "URL pointing to the related iModel."
                },
                "mapping": {
                    "$ref": "#/components/schemas/Link",
                    "description": "URL pointing to the related Mapping."
                },
                "group": {
                    "$ref": "#/components/schemas/Link",
                    "description": "URL pointing to the related Group."
                }
            }
        }
    },
    "additionalProperties": false
}

{
    "title": "CustomCalculation Response",
    "type": "object",
    "description": "Container for a CustomCalculation object.",
    "properties": {
        "customCalculation": {
            "$ref": "#/components/schemas/CustomCalculation",
            "description": "CustomCalculation properties."
        }
    },
    "additionalProperties": false
}

{
    "title": "CustomCalculation (update)",
    "type": "object",
    "description": "Properties of the CustomCalculation to be updated.",
    "properties": {
        "propertyName": {
            "type": "string",
            "description": "Name of the Property (OData v4 SimpleIdentifier)."
        },
        "formula": {
            "type": "string",
            "description": "A mathematical formula which will be evaluated for each element returned by the Group's query."
        },
        "quantityType": {
            "type": "string",
            "description": "The quantity type of the CustomCalculation. One of 'Area', 'Distance', 'Force', 'Mass', 'Monetary', 'Time', 'Volume, or 'Undefined'."
        }
    },
    "additionalProperties": false
}

{
    "title": "Link",
    "type": "object",
    "description": "Hyperlink container.",
    "properties": {
        "href": {
            "type": "string",
            "description": "Hyperlink to the specific entity."
        }
    },
    "additionalProperties": false
}

{
    "type": "object",
    "description": "Contains error information.",
    "properties": {
        "code": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        },
        "target": {
            "type": "string",
            "description": "The target of the error.",
            "nullable": true
        }
    },
    "required": [
        "code",
        "message"
    ],
    "additionalProperties": true
}

{
    "type": "object",
    "title": "Error Response",
    "description": "Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.",
    "properties": {
        "error": {
            "description": "Error information.",
            "$ref": "#/components/schemas/Error"
        }
    },
    "required": [
        "error"
    ],
    "additionalProperties": false
}