Creates a group. A group is a collection of design elements from an iModel represented by an ECSQL query. When used for reporting a group represents a single output data table in a report. There are two ways to create a group.

Create a group without properties

---

To create a group without properties do not provide the source property.

Create a group from an existing group

---

To create a group from another group provide the source property. The server will create a new group and copy over all properties from the group referenced by the source property. User must have imodels_read permissions to the iModel containing the source group. Changing source group or its properties will not change the copies of them.

Provided groupName, description, query, metadata request body properties will overwrite the properties on the copied group.

Note

---

The query request body property must be provided even when copying a group. Provide the source group query in the request when copying a group if you want to keep the same query.

Group Query

---

The query parameter of a Group must be a valid ECSQL query.

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. However, it is recommended to always select at least ECInstanceId and ECClassId columns.

• 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, ECClassId FROM bis.Element is a valid query
• Assuming that class Building.Beam is a descendant of the class bis.Element, the query SELECT ECInstanceId, ECClassId 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 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 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 Element.id ECInstanceId FROM Building.BeamAspect is valid

In all other cases the provided ECSQL query is required to select ECInstanceId and ECClassId. If ECClassId is omitted, the service assumes that query selects elements from the bis.Element class or its descendants. In some cases the results might be unexpected, e.g., you assume that you are querying bis.ElementAspect but you only select ECInstanceId so the service only selects the elements that have a matching ECInstanceId. Because of this it is always recommended to select both ECInstanceId and 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 properties of groups with the same name. The result rows will be concatenated one after another. If groups are overlapping and multiple groups select the same element the result will contain duplicates.

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 iTwin 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 iTwin 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": "PhysicalElements",
    "description": "A group of physical elements",
    "query": "SELECT ECInstanceId, ECClassId FROM BisCore.PhysicalElement",
    "metadata": [{
            "key": "key1",
            "value": "value1"
        },
        {
            "key": "key2",
            "value": "value2"
        }
    ],
    "source": {
        "mappingId": "f1fe5959-35ab-467e-83b8-a679b722d80f",
        "groupId": "08f252c4-ee78-4e2b-9280-f7365400b932"
    }
}

{
    "group": {
        "id": "08f252c4-ee78-4e2b-9280-f7365400b932",
        "groupName": "PhysicalElements",
        "description": "A group of physical elements",
        "query": "SELECT ECInstanceId, ECClassId FROM BisCore.PhysicalElement",
        "metadata": [{
                "key": "key1",
                "value": "value1"
            },
            {
                "key": "key2",
                "value": "value2"
            }
        ],
        "_links": {
            "iModel": {
                "href": "https://api.bentley.com/imodels/70a3d6d3-5385-4bc3-87c4-b6bf106e1c0a"
            },
            "mapping": {
                "href": "https://api.bentley.com/grouping-and-mapping/datasources/imodel-mappings/f1fe5959-35ab-467e-83b8-a679b722d80f"
            }
        }
    }
}

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

{
    "error": {
        "code": "InsufficientPermissions",
        "message": "The user has insufficient permissions for the requested operation."
    }
}

{
    "error": {
        "code": "MappingNotFound",
        "message": "Requested Mapping is not available.",
        "target": "mappingId"
    }
}

{
    "error": {
        "code": "InvalidGroupingAndMappingRequest",
        "message": "Cannot create Group.",
        "details": [{
            "code": "MissingRequiredProperty",
            "message": "Required property is missing.",
            "target": "groupName"
        }]
    }
}

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