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:
- Queried properties
- Element properties
- 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 ofECClassName
isBeam
, then it will match anyBeam
class from any schema (e.g.Building.Beam
,Structural.Beam
, etc.) - If the value of
ECSchemaName
isBuilding
and the value ofECClassName
is*
, then it will match any class from the schemaBuilding
(e.g.Building.Beam
,Building.CurtainWall
, etc.) - If values of
ECSchemaName
andECClassName
are*
, then it will match any ECClassId (e.g.Building.Beam
,Structural.Column
, etc.) - If either value of
ECSchemaName
orECClassName
are*
, then no element aspect lookup is done
Class inheritance is checked if there is no wildcard value.
- If the value of
ECSchemaName
isBuilding
and the value ofECClassName
isStructuralMember
, then it will match any ECClassId which inheritsBuilding.StructuralMember
(e.g.Building.Beam
which inheritsBuilding.StructuralMember
,Building.Column
which inheritsBuilding.StructuralMember
, etc) - If
ECSchemaName
orECClassName
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 theECPropertyName
is set toCategory
orcategory
, 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 theECPropertyName
is set toCategory.id
, then only theid
value0x2000000000b
will be selected - If
Category
property is a navigation property and it points to a row that has a propertyCodeValue
that we want to select, theECPropertyName
should be set toCategory.CodeValue
- If
Model
property is a navigation property and it points to a row that has a propertyJsonProperties
with a value{"formatter":{"mastUnit":{"label":"m"}}}
and we want to select the master unit label, theECPropertyName
should be set toModel.JsonProperties.formatter.mastUnit.label
. The result will bem
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}.
Request parameters
The iModel Id.
The Mapping Id.
Id of the Group for which to create a new GroupProperty.
Request headers
OAuth access token with itwin-platform
scope
Setting to application/vnd.bentley.itwin-platform.v1+json
is recommended.
Request body
GroupProperty (create)
Name of the Property (OData v4 SimpleIdentifier).
The data type of the GroupProperty. One of 'Boolean', 'Double', 'Number', 'String', or 'Undefined'.
The quantity type of the GroupProperty. One of 'Area', 'Distance', 'Force', 'Mass', 'Monetary', 'Time', 'Volume, or 'Undefined'.
Example
{ "propertyName": "Code", "dataType": "String", "quantityType": "Undefined", "ecProperties": [{ "ecSchemaName": "Generic", "ecClassName": "PhysicalObject", "ecPropertyName": "Category.CodeValue", "ecPropertyType": "String" }] }
Response 200 OK
Created a new GroupProperty successfully.
{ "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" } } } }
Response 401 Unauthorized
This response indicates that request lacks valid authentication credentials. Access token might not been provided, issued by the wrong issuer, does not have required scopes or request headers were malformed.
{ "error": { "code": "HeaderNotFound", "message": "Header Authorization was not found in the request. Access denied." } }
Response 404 Not Found
Specified GroupProperty was not found.
{ "error": { "code": "GroupPropertyNotFound", "message": "Requested GroupProperty is not available.", "target": "id" } }
Response 409 Conflict
GroupProperty with the same name already exists within the Group.
{ "error": { "code": "GroupPropertyExists", "message": "GroupProperty with this 'displayName' already exists." } }
Response 422 Unprocessable Entity
The 422 (Unprocessable Entity) status code indicates that the request cannot be processed by the server due to a client error (e.g. malformed request syntax).
{ "error": { "code": "InvalidInsightsRequest", "message": "Error message." } }
Response 429 Too many requests
This response indicates that the user has sent too many requests in a given amount of time.
{ "error": { "code": "TooManyRequests", "message": "More requests were received than the subscription rate-limit allows." } }
Response headers
The number of requests exceeds the rate-limit for the client subscription.
ECProperty
Defines a target ECProperty for a Group. This is used to determine what properties will be read from the query response of a Group.
The target ECSchema.
The target ECClass.
The target ECProperty.
The type of the target ECProperty.
{ "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 }
GroupProperty
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.
The GroupProperty Id.
Name of the Property (OData v4 SimpleIdentifier).
The data type of the GroupProperty. One of 'Boolean', 'Double', 'Number', 'String', or 'Undefined'.
The quantity type of the GroupProperty. One of 'Area', 'Distance', 'Force', 'Mass', 'Monetary', 'Time', 'Volume, or 'Undefined'.
{ "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 }
GroupProperty Response
Container for a GroupProperty object.
{ "title": "GroupProperty Response", "type": "object", "description": "Container for a GroupProperty object.", "properties": { "property": { "$ref": "#/components/schemas/GroupProperty", "description": "GroupProperty properties." } }, "additionalProperties": false }
GroupProperty (create)
Properties of the GroupProperty to be created.
Name of the Property (OData v4 SimpleIdentifier).
The data type of the GroupProperty. One of 'Boolean', 'Double', 'Number', 'String', or 'Undefined'.
The quantity type of the GroupProperty. One of 'Area', 'Distance', 'Force', 'Mass', 'Monetary', 'Time', 'Volume, or 'Undefined'.
{ "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 }
Link
Hyperlink container.
Hyperlink to the specific entity.
{ "title": "Link", "type": "object", "description": "Hyperlink container.", "properties": { "href": { "type": "string", "description": "Hyperlink to the specific entity." } }, "additionalProperties": false }
Error
Contains error information.
One of a server-defined set of error codes.
A human-readable representation of the error.
The target of the error.
{ "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 }
Error Response
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.
{ "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 }
Was this page helpful?