Table of contents
Reporting

Mappings

Download API definition:

GET https://api.bentley.com/insights/reporting/datasources/imodels/{imodelId}/mappings/{mappingId}/groups[?$top][&$continuationToken]

Gets all Groups for a Mapping.

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 insights:read.

For more documentation on authorization and how to get access token visit OAUTH2 Authorization page.

Authorization

User must have imodels_read 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.

Request parameters

Name
In
Required?
Description
imodelId
template
Yes

The iModel Id.

mappingId
template
Yes

The Mapping Id.

$top
query
No

Optional max items to be sent in response.

$continuationToken
query
No

Optional token to retrieve next page in paginated response.

Request headers

Name
Required?
Description
Authorization
Yes

OAuth access token with scope insights:read

Accept
No

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

Response 200 OK

Retrieved Groups successfully.

json
{
    "groups": [{
        "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"
            }
        }
    }],
    "_links": {
        "next": {
            "href": "https://api.bentley.com/insights/reporting/datasources/imodels/70a3d6d3-5385-4bc3-87c4-b6bf106e1c0a/mappings/f1fe5959-35ab-467e-83b8-a679b722d80f/groups/?$top=100&$continuationToken=ddac51e3-3d37-4407-816e-52b9fc80d70a"
        },
        "self": {
            "href": "https://api.bentley.com/insights/reporting/datasources/imodels/70a3d6d3-5385-4bc3-87c4-b6bf106e1c0a/mappings/f1fe5959-35ab-467e-83b8-a679b722d80f/groups/?$top=100"
        }
    }
}

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

Name
Description
retry-after

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

Group

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

TableSchema
Name
Type
Description
id
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

URL pointing to the related iModel.

_links.mapping

URL pointing to the related Mapping.

Group Collection

List of Groups.

TableSchema
Name
Type
Description
groups

List of Groups.

_links

Contains the hyperlinks to the current and next pages of results.

Link

Hyperlink container.

TableSchema
Name
Type
Description
href
String

Hyperlink to the specific entity.

Paged Response Links

URLs for redoing the current request and/or getting the next page of results if applicable.

TableSchema
Name
Type
Description
next

URL to get the next page of results.

self

URL to repeat the current request.

Error

Contains error information and an optional array of more specific errors.

TableSchema
Name
Type
Description
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.

details

Optional array of more specific errors.

Error Details

Contains error information.

TableSchema
Name
Type
Description
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
Name
Type
Description
error

Error information.