Creates a property. If group is a table, then property of that group is a column. Properties can be mapped from existing iModel ECProperties, calculated using a predefined list of calculations, or calculated using your own mathematical formula.

Source of the property value in the output is defined by the ecProperties, calculatedPropertyType, and formula values on a property. You can provide any combination of these properties. If you do not provided any of them, the output value will always be null. Such properties can be used as placeholders or to define an output schema before any property mapping is done. However, when you provide 2 or more of these properties they are evaluated in this order until a valid value (not null or undefined) is found:

1. ecProperties
2. calculatedPropertyType
3. formula

Property values are assigned during data extraction. To start the data extraction use Run Extraction operation.

Mapping ECProperties

---

Mapping property values from an iModel ECProperties to the output columns is achieved by defining the ecProperties array. It allows mapping the queried, element, element aspect, or related element properties.

The ecProperties property is a prioritized array which contains ECPropertyReference objects. The closer the ECPropertyReference is to the array's start, the higher the priority. The priority of ECPropertyReference can be changed by reordering the ecProperties array. Reading of the ecProperties array stops when a valid value is found. For example, if the ecProperties array contains two entries and the first entry results in a null or undefined value, it will take the second entry. The value can be undefined if the given ECPropertyReference references an ECProperty which does not exist. The result column will be filled with a null value if no valid value was found.

Evaluating ecProperties is prioritized by:

1. Queried properties
2. Element properties
3. Element aspect properties

Having queried properties as the highest priority allows for constant or complex values to be added to a mapping.

ECProperty lookup is defined by three values - ecSchemaName, ecClassName, and ecPropertyName.

ecSchemaName and ecClassName are used together to create an ECClassId which is the ECClassId of the current row selected by the group query. If the ECClassId of a selected row does not match the ecSchemaName and ecClassName pair, the value for this ECProperty is considered undefined. If the formed ECClassId is of an element aspect, the current selected row is an element, and there is only one instance of that element aspect related to the element, the property lookup is done on the element aspect.

Both ecSchemaName and ecClassName can be set to a wildcard value *.

• If the value of ecSchemaName is * and the value of ecClassName is Beam, then it will match any Beam class from any ECSchema (e.g. Building.Beam, Structural.Beam, etc.)
• If the value of ecSchemaName is Building and the value of ecClassName is *, then it will match any class from the ECSchema Building (e.g. Building.Beam, Building.CurtainWall, etc.)
• If values of ecSchemaName and ecClassName are *, then it will match any ECClassId (e.g. Building.Beam, Structural.Column, etc.)
• If either value of ecSchemaName or ecClassName are *, then no element aspect lookup is done

Class inheritance is checked if there is no wildcard value.

• If the value of ecSchemaName is Building and the value of ecClassName is StructuralMember, then it will match any ECClassId which inherits Building.StructuralMember (e.g. Building.Beam which inherits Building.StructuralMember, Building.Column which inherits Building.StructuralMember, etc.)
• If ecSchemaName or ecClassName is a wildcard, then inheritance will not be checked

Set ecPropertyName to a ECProperty name that you want to select. The value of ecPropertyName can also be a path defining how to find an ECProperty. The path segments must be separated by a period (.). The path can contain the names of:

• A navigation property
• A struct property
• A string property that happens to contain a string representation of a json object
• A property inside the selected json

Names of properties are not case sensitive. If json object does not have duplicate property names which only differ in letter casing, then those json properties are not case sensitive. We recommend treating json properties as case sensitive.

• If Category property is a navigation property with a value of {"id":"0x2000000000b","relClassName":"BisCore.GeometricElement3dIsInCategory"} and the ecPropertyName is set to Category or category, then the whole value {"id":"0x2000000000b","relClassName":"BisCore.GeometricElement3dIsInCategory"} will be selected
• If Category property is a navigation property with a value of {"id":"0x2000000000b","relClassName":"BisCore.GeometricElement3dIsInCategory"} and the ecPropertyName is set to Category.id, then only the id value 0x2000000000b will be selected
• If Category property is a navigation property and it points to a row that has a property CodeValue that we want to select, the ecPropertyName should be set to Category.CodeValue
• If Model property is a navigation property and it points to a row that has a property JsonProperties with a value {"formatter":{"mastUnit":{"label":"m"}}} and we want to select the master unit label, the ecPropertyName should be set to Model.JsonProperties.formatter.mastUnit.label. The result will be m

Calculation types

---

Property can be configured to calculate various element dimensions by setting the calculatedPropertyType value.

List of all available calculation types:

• Length - calculation of a linear element length or a perimeter of a geometric element that does not have a volume. For elements that have a volume use BoundingBox calculations to approximate the length.
• Area - calculation of a geometric element's surface area.
• Volume - calculation of a geometric element's volume.
• BoundingBoxLongestEdgeLength - calculation that gives the longest edge length of an element aligned bounding box.
• BoundingBoxIntermediateEdgeLength - calculation that gives the edge length that is not the longest nor the shortest of an element aligned bounding box.
• BoundingBoxShortestEdgeLength - calculation that gives the shortest edge length of an element aligned bounding box.
• BoundingBoxDiagonalLength - calculation that gives the distance between 2 opposite corners of the element aligned bounding box.
• BoundingBoxLongestFaceDiagonalLength - calculation that gives the longest distance between 2 opposite corners of a face on the element aligned bounding box.
• BoundingBoxIntermediateFaceDiagonalLength - calculation that gives the distance between 2 opposite corners of a face on the element aligned bounding box that is not the longest nor the shortest.
• BoundingBoxShortestFaceDiagonalLength - calculation that gives the shortest distance between 2 opposite corners of a face on the element aligned bounding box.

Calculation types that start with BoundingBox use element aligned bounding boxes. They can be used for approximations of geometric element dimensions when there are no available properties that would have exact dimensions. Some errors may occur due to bounding boxes not being a perfect fit for the surrounded element.

Custom calculations

---

Property can be configured to evaluate a custom mathematical formula that you provide by setting the formula property.

The formula supports using other group properties as variables. Recursive formulas are not supported, i.e., formula containing a variable X is not supported inside a property with a propertyName equal to X.

Supported data types:

• Double - describes a real number. When converted to a boolean value in logical operators 0 becomes false and all other values become true
• Integer - describes an integer 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

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

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

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 iTwin 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 iTwin 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": "BeamVolume",
    "dataType": "Double",
    "quantityType": "Volume",
    "ecProperties": [{
        "ecSchemaName": "*",
        "ecClassName": "*",
        "ecPropertyName": "Volume"
    }],
    "calculatedPropertyType": "Volume",
    "formula": "Length * CrossSectionArea"
}

{
    "property": {
        "id": "1ba1f4dd-efc1-4bd1-86f0-a69a4f0d4743",
        "propertyName": "BeamVolume",
        "dataType": "Double",
        "quantityType": "Volume",
        "ecProperties": [{
            "ecSchemaName": "*",
            "ecClassName": "*",
            "ecPropertyName": "Volume"
        }],
        "calculatedPropertyType": "Volume",
        "formula": "Length * CrossSectionArea",
        "_links": {
            "iModel": {
                "href": "https://api.bentley.com/imodels/70a3d6d3-5385-4bc3-87c4-b6bf106e1c0a"
            },
            "mapping": {
                "href": "https://api.bentley.com/grouping-and-mapping/datasources/imodel-mappings/f1fe5959-35ab-467e-83b8-a679b722d80f"
            },
            "group": {
                "href": "https://api.bentley.com/grouping-and-mapping/datasources/imodel-mappings/f1fe5959-35ab-467e-83b8-a679b722d80f/groups/08f252c4-ee78-4e2b-9280-f7365400b932"
            }
        }
    }
}

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

{
    "error": {
        "code": "InsufficientPermissions",
        "message": "The user has insufficient permissions for the requested operation."
    }
}

{
    "error": {
        "code": "MappingNotFound",
        "message": "Requested Mapping is not available.",
        "target": "mappingId"
    }
}

{
    "error": {
        "code": "PropertyExists",
        "message": "Property 'BeamVolume' already exists.",
        "target": "propertyName"
    }
}

{
    "error": {
        "code": "InvalidGroupingAndMappingRequest",
        "message": "Cannot create Property.",
        "details": [{
            "code": "MissingRequiredProperty",
            "message": "Required property is missing.",
            "target": "propertyName"
        }]
    }
}

{
    "error": {
        "code": "RateLimitExceeded",
        "message": "The client sent more requests than allowed by this API for the current tier of the client."
    }
}