Create Group - Reporting | iTwin Platform

REST API Overview

Reference

Reporting

Download API definition:

POST https://api.bentley.com/insights/reporting/datasources/imodels/{imodelId}/mappings/{mappingId}/groups

Creates a Group for an iModel data source Mapping. A Group is a collection of design elements from an iModel represented by an ECSQL query and defines one table in the output data of a report.

Group Query

The query parameter of a Group supports ECSql and ECClassIds.

If a valid ECSql query is given and the selected class is bis.Element, or if it is a descendant of the class bis.Element, the only required column is ECInstanceId.

SELECT * FROM bis.Element is a valid query
Assuming that class Building.Beam is a descendant of the class bis.Element, the query SELECT * FROM Building.Beam is a valid query
SELECT ECInstanceId FROM bis.Element is a valid query
Assuming that class Building.Beam is a descendant of the class bis.Element, the query SELECT ECInstanceId FROM Building.Beam is valid
SELECT ECClassId FROM bis.Element is not a valid query because ECInstanceId column is missing
Assuming that class Building.Beam is a descendant of the class bis.Element, the query SELECT ECClassId FROM Building.Beam is not valid because ECInstanceId column is missing
Assuming that Building.BeamAspect is an aspect, the query SELECT A.ECInstanceId FROM bis.Element E JOIN Building.BeamAspect A ON A.Element.id = E.ECInstanceId is not valid because the selected ECInstanceId is of the aspect, not the element
Assuming that Building.BeamAspect is an aspect, the query SELECT A.Element.id FROM Building.BeamAspect is not valid because the selected column's name is not ECInstanceId
Assuming that Building.BeamAspect is an aspect, the query SELECT A.Element.id ECInstanceId FROM Building.BeamAspect is valid

In all other cases when providing an ECSql query it is required to select ECInstanceId, ECClassId, and all other columns that you are planning to use for mapping. If only ECInstanceId and ECClassId are selected and other columns are used for mapping, those columns will be filled with null values. If either ECInstanceId or ECClassId column is not selected, the query will not produce any output.

If the query parameter does not contain a valid ECSql query, then it must be equal to bis.Element, bis.ElementAspect, or any of their descendants.

The ECClassId format {schemaName}:{schemaItemName} where schemaName does not contain a 3-part version number is supported.

The ECClassId format {schemaName}.{schemaItemName} is supported.

The ECClassId format {schemaAlias}:{schemaItemName} where schemaAlias is the alias of a schemaName is supported.

The ECClassId format {schemaFullName}:{schemaItemName} where schemaFullName contains a 3-part version number is not supported.

When the given ECClassId is equal to bis.Element or is one of its descendants, then all elements with the ECClassId will be selected.

When the given ECClassId is equal to bis.ElementAspect or is one of its descendants, then all elements that have such aspect will be selected.

When the given ECClassId is none of the above, the query will not produce any output.

If a class Building.Beam does not have any subclasses and the query parameter is set to Building.Beam, then all elements with ECClassIds of Building.Beam will be selected
If there is a class Building.StructuralMember which has 2 subclasses Building.Beam and Building.Column, and the query parameter is set to Building.StructuralMember, then all elements with ECClassIds of Building.StructuralMember, Building.Beam, and Building.Column will be selected
If a class Building.BeamAspect inherits from a class bis.ElementAspect (is unique or multi aspect) and the query parameter is set to Building.BeamAspect, then all elements that have a Building.BeamAspect attached to them will be selected. This query will not select the aspects themselves, but the elements that they are attached to. The selected elements may have any ECClassId
If there is class Building.StructuralMemberAspect which has 2 subclasses Building.BeamAspect and Building.ColumnAspect, the Building.StructuralMemberAspect class inherits from a class bis.ElementAspect (is unique or multi aspect) and the query parameter is set to Building.StructuralMemberAspect, then all elements that have Building.StructuralMemberAspect, Building.BeamAspect, or Building.ColumnAspect attached to them will be selected. This query will not select the aspects themselves, but the elements that they are attached to. The selected elements may have any ECClassId

If different queries are needed for a single output table, then create multiple Groups with those different queries but with the same name for each Group. That will cause results of all these queries to be concatenated into a single output table. The output table will have column list equal to a union of all GroupProperties of Groups with the same name.

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

template

Yes

The iModel Id.

mappingId

template

Yes

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

Request headers

Authorization

Yes

OAuth access token with itwin-platform scope

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

Request body

Group (create)

groupName

String

Name of the Group (OData v4 SimpleIdentifier).

description

String

Description of the Group.

query

String

Query string that will be executed against the target iModel to build this Group.

Example

json

{
    "groupName": "Physical elements",
    "description": "A group of physical elements",
    "query": "SELECT * FROM BisCore.PhysicalElement"
}

Response

Response 200 OK

Created a new Group successfully.

json

{
    "group": {
        "id": "08f252c4-ee78-4e2b-9280-f7365400b932",
        "groupName": "Physical elements",
        "description": "A group of physical elements",
        "query": "SELECT * FROM BisCore.PhysicalElement",
        "_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"
            }
        }
    }
}

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 Group was not found.

json

{
    "error": {
        "code": "GroupNotFound",
        "message": "Requested Group is not available.",
        "target": "id"
    }
}

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

Group

Defines a single Group (collection of iModel elements) in an iModel Mapping.

TableSchema

String

The Group Id.

groupName

String

Name of the Group (OData v4 SimpleIdentifier).

description

String

Description of the Group.

query

String

Query string that will be executed against the target iModel to build this Group.

_links.imodel

Link

URL pointing to the related iModel.

_links.mapping

Link

URL pointing to the related Mapping.

Group Response

Container for a Group object.

TableSchema

group

Group

Group properties.

Group (create)

Properties of the Group to be created.

TableSchema

groupName

String

Name of the Group (OData v4 SimpleIdentifier).

description

String

Description of the Group.

query

String

Query string that will be executed against the target iModel to build this Group.

Link

Hyperlink container.

TableSchema

href

String

Hyperlink to the specific entity.

Error

Contains error information.

TableSchema

code

String

One of a server-defined set of error codes.

message

String

A human-readable representation of the error.

target

String

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.

TableSchema

error

Error

Error information.