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

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

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

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

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

{
    "error": {
        "code": "InvalidInsightsRequest",
        "message": "Error message."
    }
}

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

{
    "title": "Group",
    "type": "object",
    "description": "Defines a single Group (collection of iModel elements) in an iModel Mapping.",
    "properties": {
        "id": {
            "type": "string",
            "description": "The Group Id."
        },
        "groupName": {
            "type": "string",
            "description": "Name of the Group (OData v4 SimpleIdentifier)."
        },
        "description": {
            "type": "string",
            "description": "Description of the Group."
        },
        "query": {
            "type": "string",
            "description": "Query string that will be executed against the target iModel to build this Group."
        },
        "_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."
                }
            }
        }
    },
    "additionalProperties": false
}

{
    "title": "Group Response",
    "type": "object",
    "description": "Container for a Group object.",
    "properties": {
        "group": {
            "$ref": "#/components/schemas/Group",
            "description": "Group properties."
        }
    },
    "additionalProperties": false
}

{
    "title": "Group (create)",
    "type": "object",
    "description": "Properties of the Group to be created.",
    "properties": {
        "groupName": {
            "type": "string",
            "description": "Name of the Group (OData v4 SimpleIdentifier)."
        },
        "description": {
            "type": "string",
            "description": "Description of the Group."
        },
        "query": {
            "type": "string",
            "description": "Query string that will be executed against the target iModel to build this Group."
        }
    },
    "additionalProperties": false
}

{
    "title": "Link",
    "type": "object",
    "description": "Hyperlink container.",
    "properties": {
        "href": {
            "type": "string",
            "description": "Hyperlink to the specific entity."
        }
    },
    "additionalProperties": false
}

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

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