Creates a GroupProperty for a Group. Each GroupProperty defines a column of mapped data.

Mapping ECProperties

---

GroupProperties define mappings from ECProperties on an iModel to columns. They allow mapping the queried, element, element aspect, or related element properties.

Content of the columns depend on the ecProperties field. The ecProperties field is a prioritized array which contains ECProperty entities. The closer the ECProperty is to the array's start, the higher the priority. The priority of ECProperty 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 ECProperty 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 four values - ECSchemaName, ECClassName, ECPropertyName and ECPropertyType.

ECSchemaName and ECClassName are used together to create a ECClassId which is the ECClassId of the current row when selecting a property. 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.

ECSchemaName and ECClassName are case-insensitive.

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 schema (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 schema 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 property name that you want to select. The value of ECPropertyName can also be a path defining how to find a property. 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

ECPropertyType is case sensitive and corresponds to the data type of a ECProperty you want to select. Supported Type values are:

• Boolean - describes a logical value which is either true or false,
• Number - treated the same as Double,
• Integer - describes a whole number,
• Double - describes a real number,
• String - describes text.

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": "Code",
    "dataType": "String",
    "quantityType": "Undefined",
    "ecProperties": [{
        "ecSchemaName": "Generic",
        "ecClassName": "PhysicalObject",
        "ecPropertyName": "Category.CodeValue",
        "ecPropertyType": "String"
    }]
}

{
    "property": {
        "id": "1ba1f4dd-efc1-4bd1-86f0-a69a4f0d4743",
        "propertyName": "Code",
        "dataType": "String",
        "quantityType": "Undefined",
        "ecProperties": [{
            "ecSchemaName": "Generic",
            "ecClassName": "PhysicalObject",
            "ecPropertyName": "Category.CodeValue",
            "ecPropertyType": "String"
        }],
        "_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/08f252c4-ee78-4e2b-9280-f7365400b932"
            }
        }
    }
}

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

{
    "error": {
        "code": "GroupPropertyNotFound",
        "message": "Requested GroupProperty is not available.",
        "target": "id"
    }
}

{
    "error": {
        "code": "GroupPropertyExists",
        "message": "GroupProperty with this 'displayName' already exists."
    }
}

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

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

{
    "title": "ECProperty",
    "type": "object",
    "description": "Defines a target ECProperty for a Group. This is used to determine what properties will be read from the query response of a Group.",
    "properties": {
        "ecSchemaName": {
            "type": "string",
            "description": "The target ECSchema."
        },
        "ecClassName": {
            "type": "string",
            "description": "The target ECClass."
        },
        "ecPropertyName": {
            "type": "string",
            "description": "The target ECProperty."
        },
        "ecPropertyType": {
            "type": "string",
            "description": "The type of the target ECProperty."
        }
    },
    "additionalProperties": false
}

{
    "title": "GroupProperty",
    "type": "object",
    "description": "Defines a one-to-many property mapping to a set of ECProperties for a Group - to be used when a Group query will return data from multiple ECClasses.",
    "properties": {
        "id": {
            "type": "string",
            "description": "The GroupProperty 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'."
        },
        "quantityType": {
            "type": "string",
            "description": "The quantity type of the GroupProperty. One of 'Area', 'Distance', 'Force', 'Mass', 'Monetary', 'Time', 'Volume, or 'Undefined'."
        },
        "ecProperties": {
            "type": "array",
            "description": "List of ECProperties that map to this GroupProperty.",
            "items": {
                "$ref": "#/components/schemas/ECProperty"
            }
        },
        "_links": {
            "type": "object",
            "description": "Contains contextual hyperlinks to related data.",
            "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": "GroupProperty Response",
    "type": "object",
    "description": "Container for a GroupProperty object.",
    "properties": {
        "property": {
            "$ref": "#/components/schemas/GroupProperty",
            "description": "GroupProperty properties."
        }
    },
    "additionalProperties": false
}

{
    "title": "GroupProperty (create)",
    "type": "object",
    "description": "Properties of the GroupProperty to be created.",
    "properties": {
        "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'."
        },
        "quantityType": {
            "type": "string",
            "description": "The quantity type of the GroupProperty. One of 'Area', 'Distance', 'Force', 'Mass', 'Monetary', 'Time', 'Volume, or 'Undefined'."
        },
        "ecProperties": {
            "type": "array",
            "description": "List of ECProperties that map to this GroupProperty.",
            "items": {
                "$ref": "#/components/schemas/ECProperty"
            }
        }
    },
    "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
}