Reporting

Mappings

Download API definition:

POST https://sampleHostName/insights/reporting/datasources/imodels/{imodelId}/mappings/{mappingId}/groups/{groupId}/properties

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 three values - ECSchemaName, ECClassName, and ECPropertyName.

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

Authentication

Requires Authorization header with valid Bearer token for scope insights:modify.

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.

Extraction row limiting

Mappings created or modified by using the "Try it out" function can only extract a maximum of 100 rows for each group. Mapping modification is considered any POST/DELETE/PATCH/PUT request to any endpoint with the tag "Mappings" or if the URL contains {mappingId}.