Create GroupProperty - Reporting

REST API Overview

Reference

Reporting

Download API definition:

POST https://api.bentley.com/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:

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 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}.

Request

Request parameters

imodelId

Yes

The iModel Id.

mappingId

Yes

The Mapping Id.

groupId

Yes

Id of the Group for which to create a new GroupProperty.

Request headers

Authorization

Yes

OAuth access token with itwin-platform scope

Setting to application/vnd.bentley.itwin-platform.v1+json is recommended.

Request body

GroupProperty (create)

propertyName

String

Name of the Property (OData v4 SimpleIdentifier).

dataType

String

The data type of the GroupProperty. One of 'Boolean', 'Double', 'Number', 'String', or 'Undefined'.

quantityType

String

The quantity type of the GroupProperty. One of 'Area', 'Distance', 'Force', 'Mass', 'Monetary', 'Time', 'Volume, or 'Undefined'.

ecProperties

ECProperty[]

List of ECProperties that map to this GroupProperty.

Example

json

{
    "propertyName": "Code",
    "dataType": "String",
    "quantityType": "Undefined",
    "ecProperties": [{
        "ecSchemaName": "Generic",
        "ecClassName": "PhysicalObject",
        "ecPropertyName": "Category.CodeValue",
        "ecPropertyType": "String"
    }]
}

Response

Response 200 OK

Created a new GroupProperty successfully.

json

{
    "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.

json

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

Response 404 Not Found

Specified GroupProperty was not found.

json

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

Response 409 Conflict

GroupProperty with the same name already exists within the Group.

json

{
    "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).

json

{
    "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.

json

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

Response headers

retry-after

The number of requests exceeds the rate-limit for the client subscription.

Definitions

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.

ecSchemaName

String

The target ECSchema.

ecClassName

String

The target ECClass.

ecPropertyName

String

The target ECProperty.

ecPropertyType

String

The type of the target ECProperty.

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.

String

The GroupProperty Id.

propertyName

String

Name of the Property (OData v4 SimpleIdentifier).

dataType

String

The data type of the GroupProperty. One of 'Boolean', 'Double', 'Number', 'String', or 'Undefined'.

quantityType

String

The quantity type of the GroupProperty. One of 'Area', 'Distance', 'Force', 'Mass', 'Monetary', 'Time', 'Volume, or 'Undefined'.

ecProperties

ECProperty[]

List of ECProperties that map to this GroupProperty.

_links.imodel

Link

URL pointing to the related iModel.

_links.mapping

Link

URL pointing to the related Mapping.

_links.group

Link

URL pointing to the related Group.

GroupProperty Response

Container for a GroupProperty object.

property

GroupProperty

GroupProperty properties.

GroupProperty (create)

Properties of the GroupProperty to be created.

propertyName

String

Name of the Property (OData v4 SimpleIdentifier).

dataType

String

The data type of the GroupProperty. One of 'Boolean', 'Double', 'Number', 'String', or 'Undefined'.

quantityType

String

The quantity type of the GroupProperty. One of 'Area', 'Distance', 'Force', 'Mass', 'Monetary', 'Time', 'Volume, or 'Undefined'.

ecProperties

ECProperty[]

List of ECProperties that map to this GroupProperty.

Link

Hyperlink container.

href

String

Hyperlink to the specific entity.

Error

Contains error information.

code

String

One of a server-defined set of error codes.

message

String

A human-readable representation of the error.

target

String, null

The target of the error.

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.

error

Error

Error information.